n8n : résoudre « model output doesn’t fit required format »

Vous avez branché un nœud AI Agent dans n8n, vous attendez une réponse propre, et le workflow s’arrête sur « model output doesn’t fit required format ». C’est l’une des erreurs les plus fréquentes avec les agents IA dans n8n. Voici d’où elle vient et comment la régler, des solutions les plus simples aux plus fines.

D’où vient cette erreur

Dans n8n, quand vous demandez à un agent IA une sortie structurée (pour la réutiliser dans les nœuds suivants), vous attachez un Structured Output Parser. Ce parser définit le schéma attendu, par exemple un objet avec les champs nom, email et priorite. n8n vérifie alors que la réponse du modèle correspond. Si elle ne correspond pas, il lève l’erreur et bloque le workflow.

Pourquoi le modèle ne respecte pas le format

Les modèles de langage sont probabilistes : ils ne renvoient pas toujours exactement la même structure. Trois causes reviennent le plus souvent.

• Le modèle ajoute du texte autour du JSON (« Voici votre réponse : { … } »), ce qui casse le parsing.
• Le schéma est trop complexe ou ambigu : trop de champs, des types imbriqués, des noms peu clairs.
• Le prompt ne demande pas explicitement une sortie JSON conforme, donc le modèle improvise.

Comprendre cette logique change tout : on ne « répare » pas l’IA, on lui facilite la tâche.

Solution 1 : activer l’Auto-fixing Output Parser

C’est le réflexe le plus rapide. n8n propose un Auto-fixing Output Parser : si la première réponse ne respecte pas le schéma, il renvoie automatiquement la sortie au modèle en lui demandant de la corriger. Dans la majorité des cas, l’erreur disparaît sans autre intervention.

Léger surcoût (un appel supplémentaire au modèle quand ça rate), mais une fiabilité nettement meilleure.

Solution 2 : simplifier et clarifier le schéma

Plus le schéma est simple, plus le modèle le respecte. Limitez-vous aux champs réellement utiles, donnez-leur des noms explicites et précisez le type attendu. Un schéma de cinq champs clairs passe bien mieux qu’un schéma de vingt champs imbriqués.

Si vous avez besoin d’une structure riche, découpez : faites produire un premier objet simple, puis enrichissez-le dans les nœuds suivants plutôt que de tout demander au modèle d’un coup.

Solution 3 : renforcer le prompt

Dites explicitement au modèle ce que vous attendez. Une instruction claire dans le prompt système réduit énormément les écarts de format.

Le « uniquement, sans texte avant ni après » règle à lui seul une bonne partie des cas où le modèle bavarde autour du JSON.

Solution 4 : changer de modèle ou baisser la température

Si l’erreur persiste, le modèle est peut-être en cause. Les modèles les plus récents respectent mieux les sorties structurées. Baisser la température (vers 0) rend aussi les réponses plus déterministes, donc plus régulières sur le format. À l’inverse, une température élevée favorise la créativité mais déstabilise la structure.

Prévenir l’erreur durablement

• Activez l’auto-fixing par défaut sur vos agents qui produisent du JSON.
• Testez avec plusieurs entrées avant de passer en production, pas seulement le cas idéal.
• Gardez un schéma minimal et enrichissez en aval.
• Ajoutez une branche d’erreur dans le workflow pour être alerté plutôt que de tout bloquer.

Ces réflexes font la différence entre un agent qui plante un jour sur deux et un agent fiable. C’est précisément ce qu’on travaille sur vos propres workflows dans notre formation n8n.