# Dépannage

Erreurs courantes et correctif le plus rapide. Scannez le tableau pour votre symptôme, sautez à la section pour le contexte.

| Symptôme | Cause probable | Correctif |
| -------- | -------------- | --------- |
| `401` / `403` sur un webhook | Bearer token mauvais / manquant, ou trigger requiert une auth sans secret | Vérifiez la config **Auth** du nœud Webhook et l'en-tête envoyé |
| Agent renvoie `"{}"` avec JSON schema activé | Aucun input n'est arrivé au nœud | Vérifiez le payload du trigger et le câblage en amont |
| Génération d'image : `400 Unknown parameter` | Mismatch modèle/paramètre côté provider | Auto-retry avec payload corrigé — si ça persiste, changez de modèle |
| Credential illisible (`404` au déchiffrement) | Le credential stocké est devenu illisible | Recréez le credential ; si ça persiste, contactez le support |
| Outil Shell : `command not found` | Binaire absent de l'image sandbox | Ajoutez-le à l'image, ou utilisez un autre outil |
| `429` sur `/execute/start` | Quota de runs par user atteint | Attendez le renouvellement de la fenêtre, ou upgradez |
| Trigger se déclenche mais l'input est vide | Mauvaise config de trigger, ou clé de dédoublonnage qui filtre | Inspectez l'onglet Runs ; revérifiez config + dedupe key |
| `400` à la sauvegarde du workflow | Une règle structurelle est violée (2 triggers, trigger + Start, webhook non authentifié, Respond mal placé) | Lisez l'erreur ; corrigez le point d'entrée / le nœud Respond |
| Workflow Doctor signale un nœud deprecated | Le workflow utilise un type de nœud marqué deprecated dans le registry | Appliquez la migration suggérée, ou remplacez-le manuellement par le nœud recommandé |
| Impossible de passer un workflow en **Live** | Un nœud n'est pas encore exécutable (Agent sans instructions, HTTP sans URL, …) | Ouvrez le nœud signalé et remplissez le champ manquant |

## Webhook renvoie 401 ou 403

Le déclencheur Webhook échoue en mode fermé. Si `authType` est différent de `none` et qu'aucun secret n'est configuré, chaque appel renvoie `401`.

- **`401 Invalid webhook credentials`** — En-tête manquant, malformé ou ne matche pas le secret configuré. Envoyez exactement :
  - `Authorization: Bearer <token>` pour `bearerSecret`
  - Le nom d'en-tête configuré (défaut `X-API-Key: <token>`) pour `apiKeySecret`
- **`403`** sur un appel API publié — Soit la surface API est désactivée, soit l'agent est inactif, soit la clé agent a été révoquée. Vérifiez l'espace Production → Deploy → API → liste des clés.

## L'Agent renvoie "{}" ou JSON vide

Quand un Agent a la **sortie structurée (JSON schema)** activée et que les champs en aval sont vides, l'input n'est jamais arrivé au modèle.

- Confirmez que le trigger s'est bien déclenché (onglet Runs → dépliez la ligne → bloc **Input**).
- Si l'input du trigger contient la donnée mais l'Agent affiche `{}` — votre **template d'input** dans l'Agent référence probablement un chemin inexistant. Utilisez **Test with fixture** dans l'éditeur et regardez le prompt résolu.
- Si le modèle a renvoyé du texte qui ne matche pas le schéma, le run échoue avec une erreur de validation (pas un `{}` silencieux).

## Génération d'image : 400 "Unknown parameter"

Apparaît quand le modèle/provider n'accepte pas un paramètre d'une autre version d'API (ex. `response_format` sur un modèle qui utilise `output_format`).

L'exécuteur réessaie une fois avec le payload corrigé — la plupart du temps vous ne verrez l'erreur que dans les logs, jamais dans le run. Si ça persiste :

- Changez de modèle dans la config du nœud.
- Vérifiez la liste de paramètres actuels du provider.
- Ouvrez un bug — nous maintenons la map à jour.

## Credential illisible (404 au déchiffrement)

Un credential stocké est devenu illisible. Symptômes :

- Des nœuds qui marchaient avant affichent maintenant "credential not found".

Correctif :

1. Ouvrez la page Credentials.
2. Supprimez le credential concerné.
3. Recréez-le (même nom) avec le secret.
4. Relancez.

Si recréer le credential ne résout pas le problème, contactez le support avec votre `run_id`.

## Outil Shell : "command not found"

La sandbox tourne une image Alpine minimale. `bash`, `curl`, `jq`, `python3` sont présents ; `node`, `gcc`, CLI exotiques non.

Options :

- Ajoutez le binaire à votre image sandbox (`apk add <pkg>`) et reconstruisez.
- Utilisez plutôt l'outil Code Interpreter — Python + numpy/pandas/requests préinstallés.
- Réécrivez l'étape comme un appel HTTP vers un service qui a déjà le binaire.

Ne désactivez jamais la sandbox pour "corriger" ça. La sandbox est une frontière de sécurité, pas une gêne CI.

## 429 sur /execute/start

Quota d'exécution par user atteint. La réponse inclut un en-tête `Retry-After` (secondes) et un body JSON :

```json
{ "detail": "Execution quota exceeded. Try again in 312s." }
```

Correctif :

- Attendez le renouvellement de la fenêtre.
- Réduisez la fréquence du trigger (cron du nœud Schedule, ou dedupe webhook).
- Upgradez votre plan.
- Pour une boucle qui s'emballe, tuez le run fautif depuis l'onglet **Production** (Cancel).

## Le trigger s'est déclenché mais l'input est vide

Deux causes courantes :

1. **La config du trigger n'extrait pas le bon champ.** Ouvrez le trigger, cliquez **Fetch real event**, regardez le payload live. Assurez-vous que votre **mapping d'input** (ou template) référence un chemin qui existe.
2. **La clé de dédoublonnage a filtré l'événement.** Les triggers (surtout Gmail, Notion, HTTP poll) maintiennent un set de dédoublonnage. Si vous avez repointé le trigger vers une nouvelle source mais gardé l'ancienne dedupe key, les événements neufs ressemblent à du "déjà vu".

Correctif :

- Modifiez la dedupe key (tout changement reset le set).
- Ou videz l'état de dédoublonnage du trigger depuis l'onglet **Production**.

## 400 à la sauvegarde du workflow

La sauvegarde lance une validation structurelle. Une règle bloquante renvoie `400` et le workflow n'est pas sauvé. Le message nomme la règle ; les causes habituelles :

- **Plus d'un nœud trigger.** Un workflow a exactement une entrée — gardez un seul Webhook / Schedule / Event listener.
- **Un nœud trigger mélangé à un nœud Start.** Choisissez un point d'entrée : un trigger publié *ou* un Start manuel/API, pas les deux.
- **Webhook en `authType: none`, ou sans path.** Les webhooks doivent être authentifiés et avoir un path — définissez un type d'auth (bearer / clé API) et une route.
- **Nœud Respond mal placé.** Un seul nœud Respond est autorisé, et seulement avec un trigger Webhook ou une entrée Start. Avec un trigger Schedule ou Event listener il n'y a aucun appelant à qui répondre, donc il est rejeté.

Un **nœud orphelin** (sans connexion entrante et qui n'est pas l'entrée) n'est qu'un **avertissement** — la sauvegarde passe, mais ce nœud ne s'exécute jamais. Câblez-le ou supprimez-le. Voir [Règles de validation](#/concepts).

## Workflow Doctor signale un nœud deprecated

Les nœuds deprecated peuvent encore exister dans d'anciens workflows, mais ils ne doivent plus être utilisés pour les nouveaux changements. Workflow Doctor lit les métadonnées de compatibilité du node registry et signale les types de nœuds deprecated comme avertissements.

Correctif :

- Utilisez l'action de migration quand Workflow Doctor en propose une.
- Si aucune migration automatique n'est disponible, remplacez le nœud par le successeur recommandé et recâblez les mêmes entrées et sorties.
- Sauvegardez une version avant la migration pour pouvoir comparer ou restaurer l'ancien graphe.

## Impossible d'activer / passer en Live

Les nouveaux workflows démarrent en **Draft**. Le passage en **Live** lance un contrôle d'activation : chaque nœud doit être exécutable. Le toggle est bloqué et le nœud fautif signalé quand :

- Un **Agent** n'a pas d'instructions (system prompt vide).
- Une **HTTP Request** n'a pas d'URL.
- Un **Send Email** n'a pas de destinataire.
- Un **Sub-workflow** n'a pas de workflow cible sélectionné.

Correctif :

1. Ouvrez le nœud signalé.
2. Remplissez le champ manquant (system prompt / URL / destinataire / cible).
3. Sauvegardez, puis repassez en **Live**.

C'est distinct de la validation structurelle à la sauvegarde ci-dessus — un workflow peut se sauver en Draft tout en restant incomplet à l'exécution.

## Isolation de la sandbox

`Shell` et `Code Interpreter` s'exécutent dans une sandbox isolée garantie par la plateforme — chaque appel obtient un environnement éphémère sans accès aux chemins de l'hôte, aux données d'autres utilisateurs ni aux métadonnées cloud. Vous n'avez rien à configurer ; c'est toujours actif.

Si un outil sandboxé semble voir quelque chose qu'il ne devrait pas, contactez le support avec votre `run_id`.

## Toujours bloqué

- **L'onglet Runs** est votre ami — chaque run enregistre input, output, erreur et le nœud précis qui a échoué (`failed_node_label`).
- Pour les problèmes plateforme, consultez la status page ou contactez le support avec votre `run_id`.

---

*Source: https://agentbuilder.systalink.sn/docs/troubleshooting — human documentation.*
*Other language: [/docs-md/en/troubleshooting.md](/docs-md/en/troubleshooting.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*