n8n validatie-expert

Dit bestand is door ToolBrain vertaald en inhoudelijk gewijzigd op 2026-08-30, op basis van n8n-validation-expert SKILL.md uit czlonkowski/n8n-skills (MIT), zie de bron_url hierboven en ../LICENSES/n8n-skills-MIT.txt.

Gids voor het interpreteren en oplossen van validatiefouten in n8n-workflows.

Validatiefilosofie

Vroeg en vaak valideren. Validatie is normaal gesproken een iteratief proces: reken op feedbackloops, gemiddeld 2-3 valideer-en-fix-cycli, met (uit gemeten gebruik) gemiddeld zo'n 23 seconden nadenken over de fout en 58 seconden om 'm op te lossen. Het is geen éénmalige actie — behandel het als een gesprek met de validator, niet als een eindtoets.

Ernstniveaus

1. Fouten (verplicht op te lossen) — blokkeren de uitvoering, moeten opgelost zijn vóór activatie. Typen: missing_required (verplicht veld ontbreekt), invalid_value (waarde valt buiten toegestane opties), type_mismatch (verkeerd datatype, bijv. string in plaats van getal), invalid_reference (verwezen node bestaat niet), invalid_expression (expressie-syntaxfout).

2. Waarschuwingen (aan te raden op te lossen) — blokkeren de uitvoering niet. Typen: best_practice (aanbevolen maar niet verplicht — verschijnt alleen onder de ai-friendly/ strict-profielen), deprecated (verouderde functie — verschijnt onder elk profiel), security (hardgecodeerde secrets, niet-geauthenticeerde webhooks — onder elk profiel), performance (mogelijk prestatieprobleem — adviserend, ai-friendly/strict).

3. Suggesties (optioneel) — verbeteringen die niet noodzakelijk zijn: optimization (kan efficiënter) en alternative (andere manier om hetzelfde te bereiken).

De validatielus in de praktijk

Configureer een node → valideer → lees de foutmeldingen zorgvuldig → los fouten op → valideer opnieuw → herhaal tot geldig (meestal 2-3 iteraties). Dit is normaal — laat je niet ontmoedigen door meerdere ronden. Een klein voorbeeld: eerste validatie geeft "channel ontbreekt", je vult name: "general" aan, tweede validatie geeft "text ontbreekt", je vult text: "Hallo!" aan, derde validatie is geldig.

Validatieprofielen

De vier profielen zijn cumulatief: elk profiel toont alles wat het lagere profiel toont, plus meer. De scheidslijn ligt bij best-practice-adviezen — minimal en runtime laten die weg, ai-friendly en strict voegen ze toe. Fouten zijn hetzelfde op elk profiel, behalve dat minimal een paar configuratiechecks overslaat (zoals enum-validatie van een expliciete operation). Security- en deprecation-waarschuwingen verschijnen onder elk profiel.

• minimal — snelle structurele checks tijdens het bedraden van een workflow. Toont alleen harde fouten die uitvoering zouden stoppen. Slaat enum-checks en adviezen over. Snelst en meest permissief.
• runtime (aanbevolen standaard) — de dagelijkse profielkeuze tijdens het bouwen. Toont fouten plus security- en deprecation-waarschuwingen, geen best-practice-adviezen. Gebalanceerd: vangt alles wat breekt, blijft stil over stijl.
• ai-friendly — alles van runtime, plus best-practice-adviezen (foutafhandeling ontbreekt, "webhook moet altijd antwoorden", rate-limit-opmerkingen, verouderde typeVersion-suggesties). Let op: dit profiel is strenger dan runtime, niet losser.
• strict — alles van ai-friendly, plus checks op ongebruikte properties ("property 'X' wordt niet gebruikt bij de huidige instellingen"). Maximale lint-strengheid, bruikbaar bij het hardenen van een productiekritische workflow.

Meest voorkomende foutsoorten

Vijf kernfouten, ruwweg op frequentie: missing_required (gebruik get_node om verplichte velden te zien), invalid_value (enums zijn hoofdlettergevoelig — check de toegestane lijst), type_mismatch (converteer naar het verwachte type), invalid_expression (ontbrekende {{}}, typefouten — zie de expression-syntax-skill), invalid_reference (node hernoemd, verwijderd of verkeerd gespeld — fix de naam of ruim losse verbindingen op).

Een aparte categorie, patchNodeField-fouten (veld niet gevonden, dubbelzinnige match, ongeldige/onveilige regex), verschijnt wanneer een patch-operatie faalt tijdens een partial-workflow-update — dit is bewust streng en geeft een fout in plaats van stilzwijgend door te gaan.

Automatische normalisatie

Bij elke workflow-update wordt automatisch een aantal veelvoorkomende operator-structuren genormaliseerd — vertrouw hierop, fix ze niet handmatig. Binaire operatoren (equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith) verliezen een overtollige singleValue-property; unaire operatoren (isEmpty, isNotEmpty, true, false) krijgen singleValue: true; IF/Switch-metadata krijgt de juiste conditions.options aangevuld. Wat de normalisatie NIET kan oplossen: verbindingen naar niet-bestaande nodes (ruim die apart op), mismatches in het aantal takken (verbindingen toevoegen/verwijderen), en paradoxale corrupte staten (mogelijk handmatige database-interventie nodig).

Valse positieven

Recente validator-verbeteringen hebben de klassieke valse positieven weggenomen — template literals binnen expressies, optional chaining, weggelaten operation-defaults, het Webhook-naar-Respond-to-Webhook-patroon en meer geven geen foutmelding meer. Er is geen vaste lijst met "bekende valse positieven om te negeren" meer nodig.

Wat overblijft zijn best-practice-adviezen (alleen zichtbaar onder ai-friendly/strict) die een reële afweging signaleren maar in jouw situatie prima acceptabel kunnen zijn:

• "...zonder foutafhandeling" — oké voor ontwikkel-/testomgevingen en niet-kritieke notificaties; oplossen voor productie met belangrijke data.
• "Geen retry-logica" — oké voor idempotente operaties, API's met eigen retry, handmatige triggers; oplossen voor onbetrouwbare externe diensten en productieautomatisering.
• "...rate limits en tijdelijke storingen" — oké voor interne/laagvolume/server-side gelimiteerde API's; oplossen voor publieke, hoogvolume API's.
• "Ongelimiteerde query" — oké voor kleine bekende datasets, aggregaties, ontwikkel-/test; oplossen voor productiequeries op grote tabellen.

Security- en deprecation-waarschuwingen daarentegen verschijnen onder elk profiel en moeten als serieus worden behandeld.

Structuur van een validatieresultaat

Een validatieresultaat bevat een valid-vlag, een lijst errors (elk met type, property, message, fix), een lijst warnings (elk met message en suggestion), een lijst suggestions, en een summary met tellingen. Lees het als volgt: check eerst valid, los dan errors op (verplicht), bekijk daarna warnings (per geval afwegen), en overweeg tot slot de suggestions (optioneel).

Workflowvalidatie

De workflowvalidatie controleert de hele workflow, niet alleen losse nodes: node-configuraties, verbindingen (geen kapotte referenties), expressies (syntax en referenties) en de logische structuur van de flow.

Veelvoorkomende workflowfouten:

• Kapotte verbindingen — een verbinding wijst naar een node die niet bestaat. Fix: verwijder de losse verbinding of maak de ontbrekende node aan.
• Cycli (waarschuwing, geen fout) — een cyclus in de workflow is een waarschuwing, geen harde fout: runtime-gestuurde loops (error-retry, datagedreven paginering, een router die terugvoedt) lopen gewoon door en zijn legitiem. Fix alleen als de loop onbedoeld is: zorg voor een echte uitgang (een conditie, een foutuitgang, of een begrensde teller).
• Meerdere starttriggers — slechts één trigger zal uitvoeren. Fix: verwijder overtollige triggers of splits op in aparte workflows.
• Losstaande nodes — een node is niet verbonden met de workflowflow. Fix: verbind de node of verwijder 'm.

Herstelstrategieën

• Opnieuw beginnen — bij een ernstig kapotte configuratie: noteer verplichte velden, maak een minimale geldige configuratie, breid stap voor stap uit, valideer na elke toevoeging.
• Binair zoeken — als een workflow wel valideert maar verkeerd uitvoert: verwijder de helft van de nodes, valideer en test, en herhaal tot het probleem geïsoleerd is.
• Losse verbindingen opruimen — bij "node niet gevonden"-fouten: draai een opschoon-operatie die verweesde verbindingen verwijdert.
• Auto-fix gebruiken — voor fouten die automatisch op te lossen zijn: bekijk eerst een preview van de voorgestelde fixes (zonder toepassen), en pas ze daarna toe met een gekozen betrouwbaarheidsdrempel.

Auto-fix-mogelijkheden

Automatische reparatie kan onder meer: het ontbrekende =-prefix in expressies toevoegen, niet-ondersteunde node-typeVersions downgraden, conflicterende foutinstellingen opruimen, onbekende node-types corrigeren via gelijkenis-matching (90%+ zekerheid), ontbrekende webhook-paden genereren, en slimme upgrades naar de laatste node-versie uitvoeren (met migratie waar nodig). Betrouwbaarheidsniveaus: high (90%+, veilig automatisch toe te passen), medium (70-89%, review aanbevolen), low (<70%, handmatige review verplicht).

Beste werkwijzen

Wel doen: valideren na elke significante wijziging, foutmeldingen volledig lezen, fouten één voor één oplossen, het runtime-profiel gebruiken vóór uitrol, altijd het valid-veld checken in plaats van succes aan te nemen, automatische normalisatie vertrouwen, get_node raadplegen bij twijfel over vereisten, geaccepteerde valse positieven documenteren.

Niet doen: validatie overslaan vóór activatie, alle fouten in één keer proberen op te lossen, foutmeldingen negeren, het strict-profiel gebruiken tijdens ontwikkeling (te veel ruis), aannemen dat validatie geslaagd is zonder het resultaat te checken, normalisatie-issues handmatig fixen, uitrollen met onopgeloste fouten, waarschuwingen categorisch negeren.

De workflow draaien nadat hij valideert

Validatie checkt structuur, parameters en expressies — er wordt nooit iets echt uitgevoerd. Een workflow die schoon valideert kan nog steeds falen op echte data, dus draai 'm één keer voordat je 'm klaar verklaart.

Bij een webhook-, formulier- of chattrigger: draai een testrun die de trigger automatisch detecteert en over HTTP afvuurt (de workflow moet dan actief zijn). Zonder zo'n trigger (Manual Trigger, Schedule, sub-workflow) is er geen HTTP-ingang; gebruik dan het pad met vastgezette testdata: eerst de nodes opvragen die testdata nodig hebben, dan per genoemde node één voorbeeld-item bouwen (elk item verpakt als {json: {...}}, gesleuteld op de exacte node-naam — een plat object in plaats van een array van {json}-items is hier de gebruikelijke fout), en tot slot de run met die data uitvoeren en op het resultaat wachten. Voor een snelle handmatige run zonder vastgezette data start je een directe uitvoering en poll je op het resultaat — dan voert elke node echt uit en is elke externe aanroep écht.

Toestemming vóór de eerste "echte" run. n8n weigert deze aanroepen voor een workflow die niet "beschikbaar" is gemaakt voor dit soort automatische aansturing — dat is een zichtbare, blijvende workflow-instelling, dus vraag de gebruiker om toestemming vóórdat je die aanzet.

Een bestaande workflow reviewen

Valideren tijdens het bouwen (de lus hierboven) vangt schema- en vormfouten in je eigen, nog-in-uitvoering werk. Het reviewen van een bestaande workflow — van jezelf of overgenomen van iemand anders — is een andere klus: de workflow valideert al schoon, en je zoekt naar de problemen die validatie niet ziet (stille verbindingsfouten, injectiegevoelige queries, Switch-takken die items laten vallen, Set/Code-antipatronen, ontbrekende foutpaden). Haal de workflow op en loop een ernst-gelaagde audit-checklist door (MOET OPLOSSEN / ZOU MOETEN OPLOSSEN / LEUK OM TE HEBBEN), waarbij elk punt verwijst naar de skill die de fix kent. Draai daarnaast een instantiebrede audit om hardgecodeerde secrets en niet-geauthenticeerde webhooks over de hele n8n-instantie te vinden.

Samenvatting

Validatie is iteratief (gemiddeld 2-3 cycli). Fouten moeten opgelost worden, waarschuwingen zijn optioneel. Automatische normalisatie regelt operator-structuren op de achtergrond. Gebruik standaard het runtime-profiel; stap op naar ai-friendly/strict voor best-practice-adviezen. De klassieke valse positieven zijn verholpen — overgebleven waarschuwingen zijn adviezen of security-/deprecation-meldingen, geen validatorfouten.

Praktijkvoorbeeld (NL)

Een Nederlandse groothandel in kantoorartikelen bouwt een workflow die elke ochtend voorraadmutaties vanuit hun webshop naar het boekhoudpakket synchroniseert. Bij de eerste validatieronde meldt de validator een missing_required-fout op het veld dat het boekhoudkundige grootboek aangeeft, en een security-waarschuwing omdat de API-sleutel van de boekhoudkoppeling hardgecodeerd in de node staat in plaats van als credential. Het team lost eerst de verplichte fout op, verplaatst daarna de sleutel naar de credentials-sectie, en kiest bewust voor het runtime-profiel tijdens de bouwfase zodat stijladviezen niet afleiden — pas vlak voor de livegang schakelen ze over naar strict om de workflow productierijp te maken.