Global Error Handler

1. Quoi ? — Definition et contexte

Imaginez une quarantaine de workflows N8N qui tournent en permanence — synchronisation GitHub, mises a jour Docker, notifications Telegram, pipeline de contenu. Quand l’un d’eux plante a 3h du matin, comment savoir ce qui s’est passe, si c’est grave, et quoi faire ?

Le Global Error Handler (GEH) est la reponse : un systeme centralise qui intercepte chaque erreur, la classifie automatiquement, la stocke dans une file d’attente dediee, et envoie une notification Telegram avec des boutons d’action. Un seul point d’entree pour toutes les erreurs de l’infrastructure N8N.

Dead Letter Queue

Une Dead Letter Queue (DLQ) est un concept emprunte aux systemes de messagerie : quand un message ne peut pas etre traite, au lieu d’etre perdu, il est stocke dans une file dediee pour investigation ulterieure. Ici, chaque erreur N8N devient une entree dans la DLQ avec tout son contexte.

Les 4 workflows du systeme

Workflow	Nodes	Role
Global Error Handler	19	Capture, classification, notification
GEH Callback Actions	30	Retry, analyse AI, ignore, fix
GEH Fix Applier	31	Application et rollback des correctifs AI
DLQ Weekly Digest	8	Resume hebdomadaire des erreurs

Architecture

---

2. Pourquoi ? — Enjeux et motivations

Avant le GEH, les erreurs N8N etaient silencieuses. Un workflow echouait, N8N le notait dans ses logs internes, et personne ne le savait avant de constater un dysfonctionnement. Pas de classification, pas de notification, pas de visibilite.

Problemes resolus

Probleme	Sans GEH	Avec GEH
Erreurs silencieuses	Decouvertes par hasard dans les logs	Notification Telegram immediate
Pas de contexte	”Workflow failed” sans details	Classification, node en echec, stack trace
Retry manuel	Ouvrir N8N, trouver l’execution, relancer	Bouton [Retry] dans Telegram
Pas d’historique	Erreurs perdues apres purge N8N	Dead Letter Queue persistante
Erreurs repetitives	Meme alerte en boucle	Deduplication + config par workflow

Strategie de retry a deux niveaux

Le GEH ne gere pas les retries a l’aveugle. Il s’appuie sur le retry natif de N8N au niveau de chaque node :

Niveau	Mecanisme	Quand
Node	Retry on Fail natif N8N	Erreurs transientes (timeout, 503, rate limit)
Workflow	Bouton Retry via GEH	Quand tous les retries node sont epuises

Retry on Fail natif

Chaque node HTTP, Telegram ou AI est configure avec 2-3 retries automatiques et un delai de 5-10 secondes. Si ca passe, le workflow continue normalement. Le GEH n’intervient que quand ces retries sont epuises — l’erreur est donc reellement persistante.

---

3. Comment ? — Mise en oeuvre technique

Le parcours d’une erreur

Quand un workflow echoue, voici ce qui se passe, etape par etape :

1. Capture — L’Error Trigger intercepte l’echec (y compris les erreurs d’activation).

2. Extraction — Un node Code normalise le contexte : workflow source, node en echec, message d’erreur, stack trace. Les donnees sensibles (tokens, mots de passe, connection strings) sont automatiquement masquees par une fonction redact().

3. Configuration — Le GEH consulte la table error_handling_config pour savoir si ce workflow a des regles specifiques (notifications desactivees, suppression temporaire, max retries custom).

4. Insertion DLQ — L’erreur est stockee dans la table error_dead_letter_queue avec un identifiant unique (err_<16hex>).

5. Classification — Des regles par mots-cles analysent le message d’erreur pour determiner le type et la severite :

Type detecte	Mots-cles	Severite
timeout	timeout, ETIMEDOUT, deadline	warning
network	ECONNREFUSED, ENOTFOUND, socket	warning
authentication	401, 403, unauthorized	critical
rate_limit	429, rate limit, quota	warning
data_validation	invalid, schema, parse error	info
resource	out of memory, disk full	critical
configuration	missing credential, not found	critical

6. Notification — Si les notifications sont activees pour ce workflow, le GEH appelle le Notification Hub avec un message formate et des boutons d’action.

Prevention des boucles

Le GEH lui-meme n’a pas d’Error Workflow. Si le GEH plante, ca ne declenche pas un autre GEH. Le Notification Hub, de son cote, a un fallback minimal (Telegram direct) pour eviter les cascades d’erreurs.

Les 4 actions Telegram

Quand la notification arrive sur Telegram, elle propose quatre boutons :

[Retry] — Relance l’execution echouee via l’API N8N. Avant de relancer, le systeme verifie que l’erreur est eligible au retry (can_auto_retry). Le compteur de retries est incremente dans la DLQ.

[Details] — Demande une analyse AI a Claude. La premiere demande genere l’analyse (type d’erreur, cause probable, suggestion de fix), les suivantes utilisent le cache stocke dans la DLQ. Pratique pour comprendre une erreur complexe sans ouvrir N8N.

[Ignore] — Marque l’erreur comme resolue dans la DLQ. Utile pour les faux positifs ou les erreurs ephemeres deja corrigees.

[Fix] — Fonctionnalite avancee : Claude analyse le workflow defaillant et propose un correctif automatique. Le fix est stocke comme proposition, puis un second workflow (GEH Fix Applier) gere l’application avec backup, confirmation et rollback.

Configuration par workflow

Chaque workflow peut avoir ses propres regles dans la table error_handling_config :

Parametre	Defaut	Usage
error_handling_enabled	true	Desactiver pour un workflow en maintenance
max_retries	3	Override du nombre de retries
notify_on_error	true	Couper les notifications sans couper la DLQ
auto_retry_enabled	false	Retry automatique sans intervention
suppress_until	null	Suppression temporaire (ISO timestamp)

Maintenance mode

Quand N8N se met a jour (self-update Docker), un flag de maintenance est insere dans error_handling_config pour supprimer les notifications pendant le redemarrage. Sans ca, chaque worker qui s’arrete genererait une fausse alerte.

DLQ Weekly Digest

Chaque dimanche a 9h, le workflow DLQ Weekly Digest genere un resume des erreurs de la semaine et l’envoie via le Notification Hub. Ce digest permet de reperer les patterns : un workflow qui echoue regulierement, un type d’erreur recurrent, des retries qui ne resolvent jamais le probleme.

Le digest inclut :

• Nombre total d’erreurs par severite
• Top workflows en erreur
• Erreurs non resolues (retry_status = pending/exhausted)
• Tendances par rapport a la semaine precedente

---

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
Classification par regles	Types inconnus classes “unknown”	Analyse AI on-demand via [Details]
Pas d’auto-retry	Chaque retry necessite un clic	Flag auto_retry_enabled prepare mais non deploye
Fix AI experimental	Les correctifs proposes ne sont pas toujours applicables	Double confirmation avant application + rollback automatique
Pas de correlation	Erreurs liees non groupees	Identifiable via le digest hebdomadaire

Scenarios d’evolution

Si le volume d’erreurs augmente :

• Activer l’auto-retry pour les erreurs transientes (timeout, rate limit)
• Grouper les erreurs similaires dans le digest
• Ajouter un seuil d’alerte : “5 erreurs du meme workflow en 1h = escalade”

Si besoin de correlation inter-workflows :

• Tracer les chaines d’execution (workflow A appelle B qui appelle C)
• Si C echoue, montrer le contexte complet de la chaine
• Permettre le retry depuis le workflow parent

Si l’equipe s’agrandit :

• Assignation des erreurs par domaine (Docker → ops, Odoo → business)
• Escalade si non traitee apres un delai configurable
• Dashboard Grafana avec metriques DLQ

---

Pages liees

Infrastructure

• N8N en mode Queue — Backend ou tournent les workflows
• Monitoring Stack — Prometheus et Grafana

Workflows

• Notification Hub — Routage des notifications d’erreur
• Telegram Orchestrator — Reception des callbacks Retry/Details/Ignore
• Docker Auto-Updates — Maintenance mode pendant les updates

Reference

• Glossaire — Dead Letter Queue, Error Trigger