Une exécution n8n qui échoue : la méthode de diagnostic

Un matin, une automatisation qui tournait depuis six mois s’arrête. Le bandeau rouge annonce
quelque chose comme « Cannot read properties of undefined », et vous voilà à
cliquer sur tous les nœuds en espérant comprendre. C’est le moment le plus décourageant de
l’automatisation : tout fonctionnait, plus rien ne fonctionne, et le message ne ressemble à
rien de familier.

La bonne nouvelle, c’est que ces pannes se répartissent en très peu de familles. Une fois
qu’on sait les reconnaître, le diagnostic tient en quelques minutes et se fait presque toujours
dans le même ordre. Les messages obscurs, eux, se traduisent : derrière chacun il y a une
cause banale.

Ce guide donne la méthode complète : ce que l’écran d’exécution vous dit déjà et qu’on
ne lit pas, les quatre familles d’échec et comment les distinguer en trente secondes, la
traduction des messages les plus fréquents, les réglages de nœud qui évitent la moitié des
pannes, et comment être prévenu au lieu de découvrir le problème trois jours plus tard.

Ce que l’écran vous dit déjà

Le réflexe naturel devant une exécution en échec est de relire l’automatisation. C’est
presque toujours une perte de temps : l’automatisation n’a pas changé, c’est ce qui entre
dedans qui a changé. L’écran d’exécution contient déjà les trois quarts de la réponse, à
condition de le lire dans le bon ordre.

Le nœud rouge. C’est celui qui a levé l’erreur, et le point de départ. Mais
attention : dans une majorité de cas, ce n’est pas lui le coupable. Un nœud qui envoie un
e-mail échoue parce que l’adresse qu’il a reçue est vide — la cause est en amont.

Ce qui est entré dans ce nœud. C’est la donnée la plus importante de tout
l’écran, et celle qu’on regarde en dernier. Ouvrez le nœud rouge et regardez sa colonne
d’entrée : dans la moitié des cas, le problème saute aux yeux — un champ vide, une liste à
zéro élément, un texte là où un nombre était attendu.

Le nombre d’éléments à chaque étape. n8n traite des lots. Un nœud qui reçoit
zéro élément ne s’exécute pas et n’échoue pas non plus : il ne fait rien, silencieusement.
Si votre automatisation « marche » mais n’a rien produit, c’est presque toujours qu’un
filtre en amont a tout écarté.

L’heure et la durée. Une exécution qui s’arrête à exactement cinq minutes,
ou à une durée ronde, n’a pas rencontré une erreur de logique : elle a atteint une limite
de temps. Ce n’est pas du tout le même diagnostic.

Les quatre familles d’échec

Toutes les pannes d’exécution se rangent dans quatre cases, et savoir laquelle vous concerne
détermine tout le reste. La distinction se fait en trente secondes.

La connexion. Le nœud n’a pas pu joindre le service, ou a été refusé.
Message typique : une mention d’autorisation, un code 401 ou 403. La donnée n’est pas en
cause : l’automatisation échouerait de la même façon avec n’importe quelle entrée.

La donnée. Le nœud a bien parlé au service, mais ce qu’il a reçu ou envoyé
n’a pas la forme attendue. C’est la famille la plus fréquente et la plus déroutante, parce que
l’automatisation fonctionne quatre-vingt-dix-neuf fois sur cent.

Le service distant. Rien de cassé chez vous. Le service refuse
temporairement, parce que vous allez trop vite, parce que votre quota est atteint, ou parce
qu’il a lui-même un incident. Codes 429 et 500 et suivants.

L’instance. C’est n8n lui-même qui a rendu les armes : mémoire
insuffisante, limite de durée atteinte, redémarrage en cours d’exécution. Ces pannes ne
mentionnent souvent aucun nœud, ou s’arrêtent net sans message.

Le test qui sépare les quatre est simple. Relancez la même exécution à
l’identique. Si elle passe, vous êtes dans la famille « service distant » ou
« instance ». Si elle échoue exactement pareil, c’est la connexion ou la donnée. Ce
seul geste divise le champ des possibles par deux.

La méthode en cinq temps

Voici l’ordre à suivre. Il paraît lent ; il est en réalité beaucoup plus rapide que de
cliquer partout, parce qu’il élimine des familles entières à chaque étape.

Regardez l’entrée du nœud rouge avant tout le reste. Pas sa configuration,
pas son code : ce qu’il a reçu. Vous saurez immédiatement si la donnée est en cause.

Remontez jusqu’au dernier nœud correct. Suivez les entrées vers l’amont
jusqu’à trouver l’étape où la donnée était encore conforme. Le problème est né entre ce nœud-là
et le suivant — et c’est là qu’il faut chercher, pas dans le nœud rouge.

Relancez à l’identique. Le test décrit plus haut. Il vous dit si le problème
est permanent ou passager, et cela change entièrement la suite.

Comparez avec une exécution réussie. Ouvrez la même automatisation la veille,
quand elle fonctionnait, et regardez la même étape. La différence entre les deux entrées est
littéralement la cause de la panne. C’est l’étape la plus efficace de toute la méthode, et la
plus négligée.

Isolez enfin. Si rien n’a suffi, exécutez le nœud seul avec une entrée que
vous fournissez à la main. Vous saurez alors si le nœud est mal configuré ou si c’est bien ce
qu’il reçoit qui pose problème.

L’échec de connexion : identifiants et jetons

C’est la famille la plus simple à traiter, et la plus fréquente sur les automatisations
anciennes. Un identifiant qui fonctionnait cesse de fonctionner sans que rien n’ait été touché
de votre côté.

Trois causes couvrent presque tous les cas. Le jeton a expiré : la
plupart des autorisations ont une durée de vie, et un renouvellement automatique qui finit par
échouer si personne ne s’est connecté depuis longtemps. Le mot de passe a
changé, ou l’utilisateur a été désactivé côté service. Les droits ont été
réduits : l’accès existe toujours mais ne couvre plus l’action demandée.

Le diagnostic tient en un clic : ouvrez l’identifiant dans n8n et lancez son test de
connexion. S’il échoue, vous avez votre réponse et vous n’avez plus à toucher à
l’automatisation.

Un cas particulier mérite d’être connu, parce qu’il est très déroutant : tous
les identifiants échouent d’un coup, sur toutes les automatisations. Ce n’est alors pas
un problème de service, mais de clé de chiffrement — l’instance ne parvient plus à déchiffrer ce
qu’elle a stocké. Cela arrive après une restauration incomplète, ou après un passage en
mode file d’attente où la clé n’a pas été déclarée à
l’identique partout.

L’échec de données : le champ qui n’existe pas

C’est la famille reine. Elle produit les messages les plus obscurs pour une cause presque
toujours banale : quelque chose que vous attendiez n’était pas là.

Le message « Cannot read properties of undefined » signifie exactement
ceci : vous avez demandé un champ à l’intérieur d’un objet qui n’existe pas. Vous écrivez
client.email, mais client est absent. Le message ne parle pas de
l’e-mail : il parle de ce qui devait le contenir.

Quatre situations produisent cela, dans cet ordre de fréquence.

Le service a renvoyé une liste vide. Aucune commande aujourd’hui, aucune
ligne modifiée : le nœud suivant reçoit zéro élément et l’expression tombe dans le vide.
C’est de loin la cause la plus courante, et elle apparaît toujours un jour de faible activité.

Le champ est optionnel et absent cette fois-ci. Un client sans numéro de
téléphone, une commande sans commentaire. Les cent premiers l’avaient, le cent-unième non.

La structure a changé. Le service a fait évoluer son format, et ce qui était
à la racine est maintenant dans un sous-objet. Cela arrive sans préavis, et cela casse toutes
les automatisations qui touchent ce service en même temps — c’est le signe qui permet de
l’identifier.

Le nom ne correspond pas exactement. Une majuscule, un accent, un espace de
fin. Email n’est pas email.

La parade est la même dans les quatre cas et tient en une habitude : ne jamais écrire une
expression qui suppose la présence d’un champ. Prévoyez la valeur de repli, et faites précéder
les traitements d’une vérification que la liste n’est pas vide. Deux minutes à l’écriture, contre
une panne qui se déclenchera un dimanche.

Déboguer une expression sans la deviner

Une bonne part des échecs de données ne vient pas du service mais de l’expression que vous
avez écrite pour piocher dedans. Et l’erreur affichée désigne le nœud, jamais l’expression
fautive à l’intérieur.

Le champ d’édition d’une expression affiche son résultat en direct, calculé sur l’élément
réellement présent. C’est l’outil de diagnostic le plus direct de n8n et il est sous-utilisé :
si l’aperçu affiche un résultat vide alors que vous en attendiez un, vous venez de trouver la
panne sans rien exécuter.

Deux pièges reviennent constamment. Le premier : l’expression est évaluée sur le
premier élément du lot, mais votre panne concerne le trente-septième. L’aperçu vous
rassure à tort. Passez explicitement à l’élément qui pose problème avant de conclure.

Le second : vous référencez un nœud par son nom, et ce nom a changé. n8n
ne prévient pas — l’expression devient simplement vide. C’est la panne classique après un
renommage « pour faire propre », et elle survient parfois des semaines plus tard,
quand la branche concernée s’exécute enfin.

L’échec du service distant : trop vite, trop souvent

Ici, rien n’est cassé chez vous. Le service refuse temporairement, et la bonne réaction n’est
pas de corriger quelque chose mais de ralentir.

Le code 429 signifie trop de requêtes. Chaque service fixe une limite au nombre
d’appels par minute, et une automatisation qui traite deux cents lignes d’un coup la dépasse
sans difficulté. Le symptôme caractéristique : les premiers éléments passent, les suivants
échouent tous.

Trois réponses, à combiner. Traitez par lots plutôt que tout d’un coup.
Introduisez une pause entre les lots, une seconde suffit souvent.
Activez la reprise automatique sur le nœud concerné, avec un délai croissant —
c’est un réglage, pas du code.

Les codes 500 et suivants signalent un incident chez le fournisseur. Il n’y a rien à corriger
et rien à comprendre : la seule bonne réponse est la reprise automatique, qui rattrapera
seule un incident de quelques minutes.

Le code 404 mérite une mention à part, parce qu’on le lit de travers. Il ne veut pas dire
« le service est en panne » mais « cette chose précise n’existe pas ». Un
document supprimé, un identifiant erroné, une ressource déplacée. C’est en réalité un problème
de donnée déguisé en problème de réseau.

L’échec de l’instance : mémoire et durée

Cette famille est reconnaissable à ce qu’elle ne dit rien. L’exécution s’arrête, souvent sans
nœud rouge, parfois sans message du tout.

La mémoire insuffisante se produit quand une automatisation charge un gros
volume en une fois : dix mille lignes, un fichier de plusieurs dizaines de mégaoctets, une
image traitée en mémoire. Le processus est tué par le système, et l’exécution reste en état
inachevé. La parade est le traitement par lots, jamais l’augmentation de la mémoire — elle ne
fait que déplacer le seuil.

La limite de durée se reconnaît à une durée trop ronde : exactement
cinq minutes, exactement une heure. C’est un réglage de l’instance, pas une erreur. Soit vous le
relevez, soit — et c’est presque toujours la bonne réponse — vous découpez le traitement.

Le redémarrage en cours d’exécution laisse des exécutions en état
« en cours » qui n’avancent jamais. Une mise à jour, un redéploiement, un incident
serveur. Si le cas se reproduit et que vous ne pouvez pas vous permettre de perdre des
exécutions, c’est l’un des arguments qui justifient le
mode file d’attente.

Une dernière cause, discrète mais réelle : le disque plein. Un
historique d’exécutions jamais élagué finit par saturer le serveur, et tout échoue en même temps
sans logique apparente. C’est le premier réflexe à avoir quand plusieurs automatisations sans
rapport tombent ensemble.

Rejouer une exécution sans tout relancer

Une fois la cause identifiée et corrigée, reste à rattraper ce qui n’est pas passé. n8n
permet de relancer une exécution en échec, et il y a deux façons de le faire — la différence
compte.

Relancer depuis le début rejoue toute l’automatisation avec les données
d’origine. C’est le choix par défaut, et il est dangereux si les premières étapes ont des effets
visibles : vous renverrez les e-mails déjà envoyés, vous recréerez les lignes déjà créées.

Relancer depuis le nœud en échec reprend là où ça s’est arrêté, avec les
données déjà calculées. C’est ce qu’on veut dans presque tous les cas, et c’est ce qu’on oublie
de choisir.

Un point à connaître : relancer utilise les données enregistrées, pas des
données fraîches. Si le problème venait du service distant, relancer ne rappellera pas le
service — vous rejouerez la même erreur. Dans ce cas, déclenchez une nouvelle exécution plutôt
que de relancer l’ancienne.

Avant toute relance en masse, posez-vous une seule question : que se passe-t-il si
cette étape s’exécute deux fois ? Si la réponse implique un client, une facture ou un
paiement, relancez une seule exécution d’abord et vérifiez le résultat.

Les trois réglages de nœud qui changent tout

Chaque nœud porte des réglages que presque personne n’ouvre, et qui évitent la moitié des
pannes décrites plus haut. Ils se trouvent dans l’onglet des paramètres du nœud.

Un avertissement sur le deuxième : continuer malgré l’erreur est utile pour un envoi de
notification, dangereux pour une écriture comptable. Ne l’activez que sur les étapes dont
l’échec n’a pas de conséquence, et prévoyez toujours la branche qui traite les éléments en
erreur — sinon vous ne saurez jamais qu’il y en a eu.

Être prévenu au lieu de découvrir

Le vrai problème n’est presque jamais la panne elle-même. C’est le délai entre la panne et le
moment où vous l’apprenez. Une automatisation de facturation arrêtée depuis quatre jours coûte
infiniment plus cher que la demi-heure de correction.

n8n prévoit exactement cela : une automatisation dédiée qui se déclenche quand une autre
échoue. Vous la construisez une fois, vous la désignez sur chacune de vos automatisations, et
vous ne découvrez plus jamais une panne par hasard.

Restez sobre sur son contenu. Le nom de l’automatisation, le nœud en échec, le message, le
lien vers l’exécution : quatre informations, et vous diagnostiquez depuis votre téléphone
sans ouvrir l’ordinateur.

Deux pièges à éviter. Ne faites pas dépendre l’alerte de ce qui est peut-être en
panne : si votre notification passe par le service qui a justement un incident,
vous ne serez pas prévenu. Groupez les alertes si une automatisation tourne
toutes les minutes, sinon vous recevrez six cents messages en une nuit et vous couperez le
canal — après quoi vous ne serez plus prévenu de rien.

Quand l’exécution n’apparaît pas du tout

Cas différent, et particulièrement frustrant : il n’y a pas d’erreur à diagnostiquer,
parce qu’il n’y a rien du tout dans la liste. L’automatisation était censée se déclencher, et
elle ne s’est jamais déclenchée.

Vérifiez dans cet ordre. L’automatisation est-elle active ? Un
déclencheur programmé ne fonctionne qu’à l’état actif — tester dans l’éditeur ne l’active pas, et
c’est l’oubli le plus fréquent après une modification.

Le fuseau horaire est-il celui que vous croyez ? Une instance réglée sur
le temps universel exécute votre tâche « de 8 h » à 9 h ou 10 h selon la saison. Ce
n’est pas une panne : c’est un décalage, et il se règle une fois pour toutes dans la
configuration.

Les exécutions ne sont-elles pas simplement effacées ? Si l’élagage de
l’historique est réglé sur une durée courte, une exécution réussie de la nuit peut avoir disparu
au matin. Vous cherchez alors une panne qui n’existe pas.

L’instance tournait-elle ? Une tâche programmée pendant un arrêt n’est
pas rattrapée au redémarrage. Elle est simplement perdue, sans trace.

Les webhooks qui ne déclenchent rien

Les déclencheurs par adresse méritent leur propre paragraphe, parce que leur panne la plus
courante n’en est pas une.

n8n distingue deux adresses pour chaque webhook : une adresse de test, qui n’écoute que
pendant que vous avez l’éditeur ouvert, et une adresse de production, qui fonctionne en
permanence quand l’automatisation est active. Le service extérieur a presque toujours
été configuré avec l’adresse de test. Ça marche pendant la mise au point, ça ne marche
plus le lendemain.

Ensuite, vérifiez que l’adresse publique déclarée dans la configuration correspond bien à
votre nom de domaine. Une instance qui se croit joignable sur une adresse locale distribue des
adresses de webhook que personne ne peut appeler.

Enfin, souvenez-vous que l’appel se fait de l’extérieur vers chez vous : c’est le seul
cas où votre pare-feu, votre certificat et votre reverse proxy participent au diagnostic. Un
certificat expiré fait échouer les appels sans qu’aucune trace n’apparaisse dans n8n, puisque
l’appel n’y arrive jamais.

Ce que les journaux du conteneur ajoutent

Quand l’interface ne dit rien, les journaux du conteneur disent le reste. C’est là que vivent
les pannes de la quatrième famille, celles qui ne laissent pas de trace dans les exécutions.

# Les 100 dernières lignes, en direct
docker compose logs -f --tail=100 n8n

# Le processus a-t-il été tué faute de mémoire ?
docker compose logs n8n | grep -i "out of memory\|killed\|heap"

# Depuis quand tourne-t-il ? (un redémarrage récent explique bien des choses)
docker compose ps

# Le disque est-il plein ? Première vérification quand tout tombe ensemble.
df -h /

En mode file d’attente, remplacez n8n par le nom de l’exécutant qui a traité l’exécution : le processus principal n’a rien exécuté, il n’a rien à raconter.

Trois choses s’y lisent qui ne sont visibles nulle part ailleurs : les arrêts brutaux du
processus, qui trahissent un manque de mémoire ; les erreurs de connexion à la base de
données ; et les redémarrages, qui expliquent les exécutions restées en cours.

En mode file d’attente, un réflexe supplémentaire
s’impose : lisez les journaux de l’exécutant qui a traité l’exécution, pas ceux du
processus principal. Ce dernier n’a rien exécuté, il n’a donc rien à raconter.

Éviter que ça recommence

Trois habitudes suppriment l’essentiel des pannes décrites dans cet article. Elles coûtent
quelques minutes à l’écriture de chaque automatisation.

Ne jamais supposer qu’un champ existe. Valeur de repli sur chaque expression,
vérification que la liste n’est pas vide avant tout traitement. C’est la seule habitude qui
élimine à elle seule la famille la plus fréquente.

Activer la reprise automatique sur tout nœud qui parle à un service
extérieur. Deux tentatives, quelques secondes d’écart : la quasi-totalité des incidents
passagers se règle sans que vous en entendiez parler.

Brancher une alerte dès la première mise en service, pas après le premier
incident. C’est exactement le même raisonnement que pour les sauvegardes décrites dans
sauvegarder, restaurer et migrer n8n : ce qui
échoue en silence finit toujours par échouer au pire moment.

FAQ — vos questions fréquentes

Que signifie « Cannot read properties of undefined » ?

Vous demandez un champ à l’intérieur d’un objet qui n’existe pas. Dans neuf cas sur dix, le
nœud précédent a renvoyé une liste vide, ou le champ était optionnel et absent cette fois-ci.
Regardez l’entrée du nœud rouge : la réponse y est presque toujours visible.

Mon automatisation réussit mais ne fait rien. Pourquoi ?

Elle a traité zéro élément. Un nœud qui ne reçoit rien ne s’exécute pas et ne signale aucune
erreur. Remontez la chaîne et cherchez l’étape qui affiche zéro en sortie : c’est presque
toujours un filtre trop strict, ou une recherche qui n’a rien trouvé.

Faut-il relancer depuis le début ou depuis le nœud en échec ?

Depuis le nœud en échec dans la quasi-totalité des cas. Relancer depuis le début rejoue les
étapes déjà passées : si elles envoyaient des e-mails ou créaient des lignes, elles le
referont.

Pourquoi mon automatisation ne se déclenche-t-elle pas à l’heure prévue ?

Le fuseau horaire de l’instance. Sans réglage explicite, n8n travaille en temps universel et
votre tâche de 8 h part à 9 h ou 10 h selon la saison. Cela se règle dans la configuration, pas
dans l’automatisation.

Toutes mes automatisations sont tombées en même temps. Par où commencer ?

Une panne simultanée n’est jamais une panne de logique. Regardez trois choses dans cet
ordre : l’espace disque du serveur, la clé de chiffrement si toutes échouent sur des
identifiants, et les journaux du conteneur pour vérifier un redémarrage.

Combien de temps garder l’historique des exécutions ?

Deux semaines suffisent pour diagnostiquer : au-delà, vous ne remontez jamais. Si votre
historique sert de preuve de ce qui a été envoyé à vos clients, c’est un autre besoin — et il se
traite par la sauvegarde, pas par la rétention.

Le mode « continuer malgré l’erreur » est-il recommandé ?

Seulement sur les étapes dont l’échec est sans conséquence, et à condition de traiter la
branche d’erreur. Activé partout sans discernement, il transforme des pannes visibles en pannes
invisibles — ce qui est nettement pire.

Mon webhook fonctionnait hier et ne fonctionne plus. Que vérifier ?

L’adresse. Le service extérieur a très probablement été configuré avec l’adresse de test, qui
n’écoute que pendant que l’éditeur est ouvert. Remplacez-la par l’adresse de production et
assurez-vous que l’automatisation est active.

En résumé

Une exécution qui échoue relève de quatre familles, et un seul geste en élimine deux :
relancer à l’identique. Si ça repasse, le problème était passager. Sinon, il est chez vous — et
la réponse est presque toujours dans l’entrée du nœud rouge, pas dans sa configuration.

Le réflexe le plus rentable est le quatrième de la méthode : comparer avec une exécution
réussie de la veille. La différence entre les deux entrées est la cause de la panne, et
cette comparaison prend trente secondes.

Enfin, branchez une alerte dès la mise en service. Le coût d’une panne n’est presque jamais
celui de la correction : c’est celui des jours pendant lesquels personne ne l’a vue.

Pour la suite : si vos exécutions attendent au lieu d’échouer, le sujet est traité dans
le mode file d’attente ; les erreurs rencontrées au
montage de l’instance, elles, sont dans le fichier compose
expliqué ligne par ligne.