--- title: Global Error Handler url: https://blog.guigpap.com/fr/workflows/error-handler/ url_md: https://blog.guigpap.com/fr/workflows/error-handler.md category: automation date: '2026-03-28' maturite: production techno: - n8n - telegram - claude application: - automation - operations --- # Global Error Handler > Gestion centralisee des erreurs N8N avec classification intelligente, Dead Letter Queue et retry automatique ## 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. > **Note - 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 ```mermaid flowchart TD WFs["~42 workflows N8N · Error Trigger"] subgraph GEH["Global Error Handler · 19 nodes"] direction TB Extract["Extract Error · redact secrets"] Config["Check error_handling_config"] DLQ["DLQ Insert · err_"] Classify["Classify · keyword rules"] end Hub["Notification Hub · Telegram avec boutons"] subgraph CB["GEH Callback Actions · 30 nodes"] direction TB Retry["Retry · 6n"] Details["Details AI · 9n"] Ignore["Ignore · 1n"] Fix["Fix AI · 12n"] end FixApplier["GEH Fix Applier · 31 nodes"] Digest["DLQ Weekly Digest · 8 nodes"] WFs --> Extract --> Config --> DLQ --> Classify --> Hub Hub --> CB Fix --> FixApplier DLQ --> Digest --> Hub ``` --- ## 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 | > **Tip - 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](/fr/workflows/notification-hub/) avec un message formate et des boutons d'action. > **Caution - 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) | > **Danger - 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](/fr/infrastructure/n8n-queue-mode/) — Backend ou tournent les workflows - [Monitoring Stack](/fr/infrastructure/monitoring-stack/) — Prometheus et Grafana ### Workflows - [Notification Hub](/fr/workflows/notification-hub/) — Routage des notifications d'erreur - [Telegram Orchestrator](/fr/workflows/telegram-orchestrator/) — Reception des callbacks Retry/Details/Ignore - [Docker Auto-Updates](/fr/workflows/docker-updates/) — Maintenance mode pendant les updates ### Reference - [Glossaire](/fr/reference/glossary/) — Dead Letter Queue, Error Trigger ## Metadonnees agent - Cet article est issu du blog GuiGPaP Lab. - Contexte global du blog: https://blog.guigpap.com/llms.txt - Contact auteur: https://odoo.guigpap.com/mon-cv - Licence: CC-BY-SA 4.0