
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.
| Le message que vous lisez | Ce qu’il veut dire | Où regarder |
|---|---|---|
Cannot read properties of undefined | Vous demandez un champ dans un objet qui n’existe pas. | L’entrée du nœud rouge. Neuf fois sur dix, le nœud précédent a renvoyé une liste vide. |
401 Unauthorized / 403 Forbidden | Le service refuse votre identité, ou l’action demandée. | L’identifiant dans n8n. Lancez son test de connexion : vous saurez en un clic. |
429 Too Many Requests | Vous allez trop vite pour ce service. | Rien à corriger : traitez par lots, ajoutez une pause, activez la reprise automatique. |
404 Not Found | Cette ressource précise n’existe pas. | L’identifiant que vous envoyez. C’est un problème de donnée, pas de réseau. |
500, 502, 503 | Incident chez le fournisseur, pas chez vous. | Nulle part. Activez la reprise automatique et laissez passer. |
ETIMEDOUT / ECONNREFUSED | Le service n’a pas répondu, ou la connexion a été refusée. | L’adresse appelée, puis le réseau du serveur. Fréquent sur les services internes. |
ENOTFOUND | Le nom de domaine appelé n’existe pas. | L’orthographe de l’adresse. Presque toujours une faute de frappe dans une variable. |
| Aucun message, l’exécution s’arrête net | Le processus a été interrompu. | Les journaux du conteneur. Manque de mémoire ou redémarrage. |
| L’exécution reste « en cours » indéfiniment | L’instance a redémarré pendant le traitement. | La date de redémarrage dans les journaux. Rien à corriger dans l’automatisation. |
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.
| Le réglage | Ce qu’il fait | Quand l’activer |
|---|---|---|
| Reprise automatique | Réessaie le nœud après quelques secondes, plusieurs fois. | Sur tout nœud qui parle à un service extérieur. C’est le réglage le plus rentable de la liste : il absorbe seul les incidents passagers. |
| Continuer malgré l’erreur | L’exécution se poursuit au lieu de s’arrêter, et les éléments en erreur partent sur une branche séparée. | Uniquement quand l’échec d’une étape est sans conséquence — et à condition de traiter la branche d’erreur. |
| Toujours produire une sortie | Le nœud renvoie un élément vide au lieu de rien quand il ne trouve pas de résultat. | Quand la suite doit s’exécuter même sans résultat. Évite les automatisations qui « réussissent » sans rien faire. |
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 » ?
Mon automatisation réussit mais ne fait rien. Pourquoi ?
Faut-il relancer depuis le début ou depuis le nœud en échec ?
Pourquoi mon automatisation ne se déclenche-t-elle pas à l’heure prévue ?
Toutes mes automatisations sont tombées en même temps. Par où commencer ?
Combien de temps garder l’historique des exécutions ?
Le mode « continuer malgré l’erreur » est-il recommandé ?
Mon webhook fonctionnait hier et ne fonctionne plus. Que vérifier ?
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.
Le Blueprint de l'automatisation no-code (37 pages) offert, puis un e-mail par semaine : une erreur qui coûte cher, un outil au banc d'essai, ou un cas réel décortiqué. Gratuit, désinscription en 1 clic.
