n8n-io/n8n · error · Error

Failed to parse agent steps

Error message

Failed to parse agent steps

What it means

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.

Source

Thrown at packages/@n8n/nodes-langchain/nodes/chains/ChainLLM/methods/promptUtils.ts:194

		}

		if (typeof steps === 'object' && isMessage(steps)) {
			const output = steps.text;

			const parsedOutput = (await outputParser.parse(output)) as Record<string, unknown>;
			return parsedOutput;
		}

		if (isAgentFinish(steps)) {
			const returnValues = steps.returnValues;
			const parsedOutput = (await outputParser.parse(JSON.stringify(returnValues))) as Record<
				string,
				unknown
			>;
			return parsedOutput;
		}

		throw new Error('Failed to parse agent steps');
	};

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Inspect the actual value of 'steps' at runtime (log it before the throw) to see its real shape.
2. Ensure the connected agent/model is a standard LangChain agent compatible with this node version.
3. Update @n8n/nodes-langchain and langchain to compatible versions.
4. If using a custom agent, normalize its output to one of: AgentSteps, a BaseMessage, or an AgentFinish.

Example fix

// before
throw new Error('Failed to parse agent steps');

// after — capture the shape for diagnosis
throw new Error(`Failed to parse agent steps. Got ${typeof steps}: ${JSON.stringify(steps, null, 2).slice(0, 500)}`);

function isParsableAgentStep(s: unknown): boolean {
  return isAgentSteps(s) || isMessage(s) || isAgentFinish(s);
}

try {
  const parsed = await parseSteps(steps);
} catch (e) {
  if (e instanceof Error && /Failed to parse agent steps/.test(e.message)) {
    // log steps shape, switch agent, or fall back to a direct model call
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Conversational Agent requires Chat Model
• The ‘text‘ parameter is empty.
• The ‘text‘ parameter is empty.
• The ‘prompt’ parameter is empty.
• No binary data found, please connect a binary to the input i

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/957b7c1a4ebc4ea1. Report an issue: GitHub.