n8n-io/n8n · warning · UserError

Workflow generation stopped: The AI reached the maximum numb

Error message

Workflow generation stopped: The AI reached the maximum number of steps while building your workflow. This usually means the workflow design became too complex or got stuck in a loop while trying to create the nodes and connections.

What it means

UserError thrown in handleAgentStreamError when the caught error is a LangGraph GraphRecursionError. The recursion limit is MAX_MULTI_AGENT_STREAM_ITERATIONS (set on streamConfig.recursionLimit in setupAgentAndConfigs). Hitting it means the multi-agent graph looped more times than allowed without producing a terminal state. The fixed WORKFLOW_TOO_COMPLEX_ERROR message is surfaced to the user.

Source

Thrown at packages/@n8n/ai-workflow-builder.ee/src/workflow-builder-agent.ts:648

		) {
			// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
			const messages = (await agent.getState(threadConfig)).values.messages as Array<
				AIMessage | HumanMessage | ToolMessage
			>;

			// Handle abort errors gracefully
			const abortedAiMessage = new AIMessage({
				content: 'Task aborted',
				id: crypto.randomUUID(),
			});
			// TODO: Should we clear tool calls that are in progress?
			await agent.updateState(threadConfig, { messages: [...messages, abortedAiMessage] });
			return;
		}

		// If it's not an abort error, check for GraphRecursionError
		if (error instanceof GraphRecursionError) {
			throw new UserError(WORKFLOW_TOO_COMPLEX_ERROR);
		}

		// Check for 401 expired token errors (typically from long-running generations)
		if (this.isTokenExpiredError(error)) {
			throw new UserError(WORKFLOW_TOO_COMPLEX_ERROR);
		}

		// Re-throw any other errors
		throw error;
	}

	/**
	 * Checks if the error is a 401 expired token error from the LLM provider proxy.
	 * This typically occurs during very long-running workflow generations when
	 * the AI assistant service proxy token expires.
	 *
	 * We specifically check for LangChain's MODEL_AUTHENTICATION error code to ensure
	 * we only catch authentication errors from the LLM provider, not unrelated 401s.

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Rephrase the request more specifically so the agent converges faster.
2. Break the desired workflow into smaller build steps across multiple turns.
3. If legitimate workflows routinely hit the cap, raise MAX_MULTI_AGENT_STREAM_ITERATIONS after reviewing cost/latency.
4. Check logs for repeated tool calls indicating a stuck loop and report if it persists.

// Hint at complexity up front — heuristic
const nodeCount = workflowContext?.currentWorkflow?.nodes?.length ?? 0;
if (nodeCount > 80) {
  // warn the user the request may exceed the agent's step budget
}

import { GraphRecursionError } from '@langchain/langgraph';
const isRecursionError = (e: unknown): boolean => e instanceof GraphRecursionError;

try {
  yield* builder.chat(payload);
} catch (e) {
  if (e instanceof UserError && /maximum number of steps/.test(e.message)) {
    // rephrase request into smaller steps and retry incrementally
  }
  throw e;
}

When it happens

Trigger: processAgentStream catches a GraphRecursionError from agent.stream. This happens when the supervisor/builder subgraphs keep handing control back and forth (or a tool keeps returning retryable results) until the recursion budget is exhausted.

Common situations: An ambiguous prompt makes the planner repeatedly revise; a node-creation tool fails in a way the agent retries indefinitely; a complex target workflow needs more steps than the configured ceiling; a model regression causes tool-call looping.

Related errors

• Invalid response format from templates API
• Failed to fetch template ${id}: ${response.status} ${respons
• Invalid response format from template ${id} API
• Message exceeds maximum length of ${MAX_AI_BUILDER_PROMPT_LE
• The current conversation and workflow state is too large to

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