Node Stop and Error n8n : faire échouer un workflow volontairement

Un workflow qui se termine « avec succès » après avoir enregistré une facture sans montant est plus dangereux qu'un workflow qui plante : le premier remplit votre base de déchets pendant trois semaines, le second vous alerte en une minute. Le node Stop and Error (n8n-nodes-base.stopAndError) sert à transformer une condition métier invalide en échec explicite, visible dans la liste des exécutions et capté par l'Error Workflow. Ce guide détaille ses deux modes, les patterns où il est indispensable, ceux où il n'apporte rien, et les pièges classiques.

Échouer vite plutôt que corrompre lentement

Le réflexe naturel, face à une donnée mal formée, est de la contourner : un IF, une branche vide, on passe à la suite. Mais la branche vide ne laisse aucune trace. L'exécution reste verte, et le jour où l'on s'aperçoit qu'un quart des dossiers n'est jamais parti, il faut remonter des semaines d'historique.

La littérature sur la fiabilité logicielle est sans ambiguïté. Dans « Simple Testing Can Prevent Most Critical Failures: An Analysis of Production Failures in Distributed Data-Intensive Systems », présenté à OSDI 2014 par Ding Yuan, Yu Luo, Xin Zhuang, Michael Stumm et leurs coauteurs, l'analyse de 198 pannes réelles sur Cassandra, HBase, HDFS, Hadoop MapReduce et Redis montre que 92 % des défaillances catastrophiques résultent d'une mauvaise gestion d'erreurs non fatales déjà signalées par le logiciel (voir sur Google Scholar). L'information était là ; quelqu'un l'a avalée. Stop and Error est l'outil qui empêche ce scénario dans n8n.

Ce que fait exactement le node

Stop and Error interrompt l'exécution et la marque en erreur. Deux conséquences : il n'a pas de sortie (aucun node ne peut être branché en aval, il est toujours le dernier de sa branche), et l'exécution compte comme un échec, au même titre qu'un timeout HTTP, avec sa ligne rouge dans la liste des exécutions. Le paramètre principal, Error Type, propose deux valeurs.

Error Message : la chaîne de caractères

Le champ Error Message attend un texte et accepte les expressions n8n. Tout l'intérêt est là : le message doit contenir la donnée fautive, pas une généralité.

Email invalide pour le contact {{ $json.id }} : « {{ $json.email }} » — import CRM interrompu

Un tel message se lit directement dans la notification Slack, sans ouvrir n8n ; comparez à « Erreur de validation ». Pour la syntaxe des expressions et l'accès aux nodes précédents via $('Node').item.json, voyez le guide des expressions JavaScript.

Error Object : le contexte structuré

Le champ Error Object attend un objet JSON : son champ message fournit le message d'erreur, les autres propriétés transportent du contexte exploitable en aval.

{
  "message": "Réponse API sans champ invoice_id",
  "code": "MISSING_INVOICE_ID",
  "record_id": "{{ $json.id }}",
  "http_status": "{{ $json.statusCode }}"
}

L'objet s'impose dès que l'Error Workflow doit décider plutôt qu'afficher. Avec un code métier stable, il route : MISSING_INVOICE_ID vers la comptabilité, QUOTA_EXCEEDED vers l'astreinte. Un message texte oblige à faire du pattern matching sur une chaîne — fragile dès la première reformulation.

Ce qui se passe juste après

L'erreur suit le même chemin qu'une erreur subie. Si un Error Workflow est configuré dans les Settings, n8n le déclenche et son node Error Trigger reçoit l'objet habituel :

• $json.execution.error.message — votre message, ou le champ message de votre objet ;
• $json.execution.lastNodeExecuted — le nom de votre node Stop and Error, d'où l'importance de le renommer : Stop and Error1 ne dit rien, Rejet — email invalide dit tout ;
• $json.execution.id et $json.execution.url, pour le lien direct vers l'exécution ;
• $json.workflow.id et $json.workflow.name.

Le circuit complet — Retry On Fail, option On Error, Error Trigger et alerte Slack — est détaillé dans le guide sur la gestion des erreurs. Stop and Error n'en est que la source volontaire : sans ce circuit, vous fabriquez des exécutions rouges que personne ne regarde.

Pattern 1 : le garde-fou de validation

C'est l'usage canonique. Un node IF ou Switch teste la condition métier — {{ $json.email }} is not empty, {{ $json.montant }} larger than 0 — la sortie true continue le pipeline, la sortie false finit sur un Stop and Error qui nomme l'identifiant et la valeur fautive.

L'apport par rapport à un simple filtrage est la visibilité : un item écarté par un Filter disparaît sans bruit, un item qui déclenche un Stop and Error produit une exécution rouge, une notification et une ligne d'historique. Le choix n'est pas technique, il est contractuel : une donnée invalide est-elle normale ici (il y a toujours des lignes vides dans un export) ou anormale (le fournisseur s'est engagé sur un schéma) ? Dans le premier cas, Filter suffit ; dans le second, l'échec est la bonne réponse.

Pattern 2 : la post-condition après un appel externe

Le second usage est moins connu et plus utile : vérifier après un appel qu'on a reçu ce qu'on attendait. Une API qui répond 200 OK avec un corps vide, un modèle qui renvoie du texte au lieu du JSON demandé, un webhook partenaire qui renomme silencieusement un champ — aucun de ces cas ne lève d'erreur HTTP, et le node suivant écrit undefined en base.

Un IF sur {{ $json.data?.invoice_id }} is not empty suivi d'un Stop and Error transforme ce undefined en échec net, à l'endroit exact de l'anomalie. C'est le pendant des garde-fous décrits dans le guide sur les retry et timeout du node HTTP Request : le retry protège de l'appel qui échoue, la post-condition de l'appel qui « réussit » mal. Sur les chaînes IA, où la sortie hors format domine, l'article sur les erreurs du node AI Agent détaille les vérifications à poser.

Le cas des sous-workflows

Une erreur levée dans un sous-workflow remonte au workflow parent, à condition que l'option Wait for Sub-Workflow Completion du node Execute Sub-workflow soit active — le réglage par défaut. Le parent échoue à son tour et c'est son Error Workflow qui se déclenche. Désactivez cette attente pour du « tire et oublie », et l'échec restera confiné au sous-workflow : découplage parfois voulu, rarement quand le parent dépend du résultat (voir le découpage en sub-workflows). Un Stop and Error dans un sous-workflow de validation partagé devient alors une assertion réutilisable : un seul workflow « valider un contact », appelé par cinq pipelines, qui échoue partout de la même manière.

Quand ne PAS l'utiliser

• Quand une branche à ignorer suffit : trois lignes vides dans un CSV de 4 000 ne sont pas un incident. Un Filter, ou un NoOp en bout de branche, laisse le workflow vert et le lot complet.
• Quand l'erreur est attendue et récupérable : un 429 occasionnel se traite avec Retry On Fail. Pour un enregistrement introuvable qu'on peut créer à la volée, l'option On Error → Continue (using error output) ouvre une seconde sortie sur laquelle brancher le rattrapage.
• Quand ça ne fait que polluer les statistiques : un workflow rouge à 30 % par conception n'alerte plus personne. Si votre Stop and Error se déclenche tous les jours, ce n'est plus une exception, c'est un cas nominal mal modélisé.

Cette question est ancienne. Zongwei Luo, Amit Sheth, Krys Kochut et John Miller la traitent dès 2000 dans « Exception Handling in Workflow Systems », publié dans Applied Intelligence (vol. 13, p. 125-147), : ils y séparent les exceptions système, que le moteur absorbe lui-même, des exceptions définies par l'utilisateur, inscrites dans la modélisation du processus, et rappellent que l'intervention humaine reste déterminante pour les situations qu'un moteur ne sait pas résoudre seul (voir sur Google Scholar). Stop and Error sert exactement à provoquer cette bascule vers l'humain ; utilisé pour ce qu'un retry ou un filtre traite très bien, il ne fabrique que du bruit.

Alternatives et compléments

Besoin	Outil
Écarter un item sans échouer	Node Filter, ou branche NoOp
Traiter l'échec d'un node dans le flux	On Error → Continue (using error output)
Absorber une panne transitoire	Retry On Fail (Max Tries, Wait Between Tries)
Lever une erreur depuis du code	throw new Error('…') dans un node Code
Réagir à l'échec d'un workflow	Error Trigger + Error Workflow
Tracer sans faire échouer	Node Execution Data

Le throw new Error() d'un node Code rend le même service, mais il est invisible sur le canevas : pour une règle métier que d'autres doivent voir, le node dédié gagne. Et quand la condition mérite d'être tracée sans faire échouer, le node Execution Data annote l'exécution avec des clés recherchables — un « warning » sans le rouge.

Les pièges classiques

• Le message inutilisable : « Erreur », « KO », « Données invalides » obligent à rouvrir l'exécution. Un message doit porter l'identifiant, la valeur fautive et la règle violée — c'est du débogage qu'on s'épargne.
• Le Stop and Error dans une boucle : atteint au troisième item d'un lot de cinq cents, il tue toute l'exécution. Si l'invalidité est unitaire, écartez l'item ; si elle invalide le lot, validez avant la boucle.
• Le workflow déclenché par webhook : l'échec renvoie une réponse d'erreur au client au lieu du 200 attendu — parfois voulu, parfois de quoi casser un partenaire qui retentera en boucle. Le node Respond to Webhook permet de renvoyer un code et un corps maîtrisés.
• Les effets de bord déjà commis : le node arrête la suite, il n'annule rien. Trois lignes insérées et deux emails envoyés le restent, donc le rejeu après correction doit être sûr — c'est l'affaire de l'idempotence.
• Le node non renommé : lastNodeExecuted remonte son nom, et cinq Stop and Error génériques produisent cinq alertes indiscernables.
• La règle testée nulle part : un garde-fou qui ne se déclenche jamais en test n'est qu'une hypothèse. Une validation en CI sur un jeu de données volontairement cassé confirme que la branche invalide part bien où vous croyez.

En résumé

Deux paramètres seulement — Error Type en Error Message ou Error Object, et le contenu correspondant — mais avant tout une décision de conception. Faites échouer quand la donnée viole un contrat sur lequel quelqu'un s'est engagé, et laissez Filter travailler quand l'anomalie fait partie du quotidien. Écrivez des messages qui portent la donnée fautive, passez à l'Error Object dès que l'Error Workflow doit router selon un code, renommez le node : un échec explicite ne vaut que par le circuit d'alerte qui le récupère.

Pour aller plus loin

Les garde-fous de validation prennent tout leur sens là où une donnée fausse a des conséquences durables. Le Pack Conformité & Audit (149 €) applique ce raisonnement aux traitements traçables : contrôles de complétude avant écriture, échecs explicites et journal d'incidents exploitable. Pour un traitement d'emails où chaque message doit produire un résultat vérifiable avant d'atteindre le CRM, le Pack Inbox IA (79 €) applique les mêmes post-conditions aux sorties de modèle.