{"record":{"id":"957b7c1a4ebc4ea1","repo":"n8n-io/n8n","slug":"failed-to-parse-agent-steps","errorCode":null,"errorMessage":"Failed to parse agent steps","messagePattern":"Failed to parse agent steps","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/nodes-langchain/nodes/chains/ChainLLM/methods/promptUtils.ts","lineNumber":194,"sourceCode":"\t\t}\n\n\t\tif (typeof steps === 'object' && isMessage(steps)) {\n\t\t\tconst output = steps.text;\n\n\t\t\tconst parsedOutput = (await outputParser.parse(output)) as Record<string, unknown>;\n\t\t\treturn parsedOutput;\n\t\t}\n\n\t\tif (isAgentFinish(steps)) {\n\t\t\tconst returnValues = steps.returnValues;\n\t\t\tconst parsedOutput = (await outputParser.parse(JSON.stringify(returnValues))) as Record<\n\t\t\t\tstring,\n\t\t\t\tunknown\n\t\t\t>;\n\t\t\treturn parsedOutput;\n\t\t}\n\n\t\tthrow new Error('Failed to parse agent steps');\n\t};\n","sourceCodeStart":176,"sourceCodeEnd":196,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/nodes-langchain/nodes/chains/ChainLLM/methods/promptUtils.ts#L176-L196","documentation":"Thrown at the end of the agent-step parsing function when 'steps' is neither an AgentSteps sequence, a single Message, nor an AgentFinish. The function exhausts all known step shapes and falls through to a generic Error, indicating an unexpected runtime object shape from the LangChain agent executor.","triggerScenarios":"The langchain agent executor returned a 'steps' value that does not match any of the recognized guards (isAgentSteps, isMessage, isAgentFinish). Typically a malformed agent response, an incompatible langchain version, or a custom agent whose return shape is not covered by the guards.","commonSituations":"A custom or community agent returns a non-standard steps object; langchain internals changed between versions and the type guards no longer match; the agent crashed mid-execution and returned a partial/unexpected object; a tool returned a value that confused the executor.","solutions":["Inspect the actual value of 'steps' at runtime (log it before the throw) to see its real shape.","Ensure the connected agent/model is a standard LangChain agent compatible with this node version.","Update @n8n/nodes-langchain and langchain to compatible versions.","If using a custom agent, normalize its output to one of: AgentSteps, a BaseMessage, or an AgentFinish."],"exampleFix":"// before\nthrow new Error('Failed to parse agent steps');\n\n// after — capture the shape for diagnosis\nthrow new Error(`Failed to parse agent steps. Got ${typeof steps}: ${JSON.stringify(steps, null, 2).slice(0, 500)}`);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isParsableAgentStep(s: unknown): boolean {\n  return isAgentSteps(s) || isMessage(s) || isAgentFinish(s);\n}","tryCatchPattern":"try {\n  const parsed = await parseSteps(steps);\n} catch (e) {\n  if (e instanceof Error && /Failed to parse agent steps/.test(e.message)) {\n    // log steps shape, switch agent, or fall back to a direct model call\n  } else throw e;\n}","preventionTips":["Use standard LangChain agents compatible with the node version.","Keep @n8n/nodes-langchain and langchain versions in sync.","Log the steps object shape when debugging custom agents.","Normalize custom-agent output to a recognized shape."],"tags":["langchain","agent","runtime","unexpected-shape"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}