n8n-io/n8n · error · NodeOperationError

Max iterations (${maxIterations}) reached. The agent could n

Error message

Max iterations (${maxIterations}) reached. The agent could not complete the task within the allowed number of iterations.

What it means

Thrown by checkMaxIterations on a continuation request when response.metadata.iterationCount has reached or exceeded the configured maxIterations. This enforces a cap on tool-call round-trips in the Tools Agent V3 engine loop. The check only fires on continuations (when iterationCount is defined); the first iteration is never blocked.

Source

Thrown at packages/@n8n/nodes-langchain/nodes/agents/Agent/agents/ToolsAgent/V3/helpers/checkMaxIterations.ts:38

 *   metadata: { iterationCount: 3 }
 * };
 *
 * // This will throw if iterationCount >= maxIterations
 * checkMaxIterations(response, 2, node);
 * ```
 */
export function checkMaxIterations(
	response: EngineResponse<RequestResponseMetadata> | undefined,
	maxIterations: number,
	node: INode,
): void {
	// Only check if this is a continuation (response has iteration count)
	if (response?.metadata?.iterationCount === undefined) {
		return;
	}

	if (response.metadata.iterationCount >= maxIterations) {
		throw new NodeOperationError(
			node,
			`Max iterations (${maxIterations}) reached. The agent could not complete the task within the allowed number of iterations.`,
		);
	}
}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Increase maxIterations in the Agent node options.
2. Inspect the agent's intermediate steps to identify the tool that keeps being re-invoked.
3. Improve the prompt so the model converges faster, or simplify the task.
4. Fix any tool that returns errors causing the agent to retry.

// Author-time: surface a sane default and warn if too low
const maxIterations = ctx.getNodeParameter('options.maxIterations', 0, 50) as number;
if (maxIterations < 10) {
  console.warn(`maxIterations=${maxIterations} is very low; the agent may not converge.`);
}

function isReasonableIterationCap(value: unknown): boolean {
  return typeof value === 'number' && value >= 10 && value <= 100;
}

try {
  checkMaxIterations(response, maxIterations, node);
} catch (e) {
  // Distinguish 'hit cap' from a real failure — return partial results instead of erroring
  return { ...response, stoppedAtMaxIterations: true };
}

When it happens

Trigger: The agent made maxIterations or more tool-call round-trips without finishing — e.g. the model keeps calling tools in a loop, or the task is genuinely too complex for the configured budget.

Common situations: maxIterations set very low (default overridden); the model loops on a tool that never returns a terminal answer; the task requires many sequential lookups; a misbehaving tool always returns an error causing retries.

Related errors

• Please connect a model to the Fallback Model input or disabl
• The "text" parameter is empty.
• Human-in-the-Loop nodes cannot be used inside a sub-agent. M
• The “text” parameter is empty.
• This model is not supported in ${version} version of the Age

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