{"record":{"id":"fa9f2305dfa9617a","repo":"n8n-io/n8n","slug":"max-iterations-maxiterations-reached-the-age","errorCode":null,"errorMessage":"Max iterations (${maxIterations}) reached. The agent could not complete the task within the allowed number of iterations.","messagePattern":"Max iterations \\((.+?)\\) reached\\. The agent could not complete the task within the allowed number of iterations\\.","errorType":"exception","errorClass":"NodeOperationError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/nodes-langchain/nodes/agents/Agent/agents/ToolsAgent/V3/helpers/checkMaxIterations.ts","lineNumber":38,"sourceCode":" *   metadata: { iterationCount: 3 }\n * };\n *\n * // This will throw if iterationCount >= maxIterations\n * checkMaxIterations(response, 2, node);\n * ```\n */\nexport function checkMaxIterations(\n\tresponse: EngineResponse<RequestResponseMetadata> | undefined,\n\tmaxIterations: number,\n\tnode: INode,\n): void {\n\t// Only check if this is a continuation (response has iteration count)\n\tif (response?.metadata?.iterationCount === undefined) {\n\t\treturn;\n\t}\n\n\tif (response.metadata.iterationCount >= maxIterations) {\n\t\tthrow new NodeOperationError(\n\t\t\tnode,\n\t\t\t`Max iterations (${maxIterations}) reached. The agent could not complete the task within the allowed number of iterations.`,\n\t\t);\n\t}\n}\n","sourceCodeStart":20,"sourceCodeEnd":44,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/nodes-langchain/nodes/agents/Agent/agents/ToolsAgent/V3/helpers/checkMaxIterations.ts#L20-L44","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase maxIterations in the Agent node options.","Inspect the agent's intermediate steps to identify the tool that keeps being re-invoked.","Improve the prompt so the model converges faster, or simplify the task.","Fix any tool that returns errors causing the agent to retry."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Author-time: surface a sane default and warn if too low\nconst maxIterations = ctx.getNodeParameter('options.maxIterations', 0, 50) as number;\nif (maxIterations < 10) {\n  console.warn(`maxIterations=${maxIterations} is very low; the agent may not converge.`);\n}","typeGuard":"function isReasonableIterationCap(value: unknown): boolean {\n  return typeof value === 'number' && value >= 10 && value <= 100;\n}","tryCatchPattern":"try {\n  checkMaxIterations(response, maxIterations, node);\n} catch (e) {\n  // Distinguish 'hit cap' from a real failure — return partial results instead of erroring\n  return { ...response, stoppedAtMaxIterations: true };\n}","preventionTips":["Set maxIterations high enough for the task complexity (start at 25-50).","Inspect intermediate steps when an agent hits the cap repeatedly.","Fix tools that error and cause the model to retry indefinitely."],"tags":["langchain","agent","tools-agent","iterations","loop","v3"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}