{"record":{"id":"62bafb7a6aa2b694","repo":"n8n-io/n8n","slug":"cannot-decrease-maxiterations-when-resuming-a-run","errorCode":null,"errorMessage":"Cannot decrease maxIterations when resuming a run. Expected >= ${persistedMaxIterations}, received ${callerMaxIterations}.","messagePattern":"Cannot decrease maxIterations when resuming a run\\. Expected >= (.+?), received (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/runtime/loop/agent-runtime.ts","lineNumber":407,"sourceCode":"\t\t}\n\n\t\ttry {\n\t\t\t// Merge persisted execution options with fresh caller options\n\t\t\tconst {\n\t\t\t\trunId: _rid,\n\t\t\t\ttoolCallId: _tcid,\n\t\t\t\tonResumeClaimed: _onResumeClaimed,\n\t\t\t\t...callerExecOptions\n\t\t\t} = options;\n\t\t\tconst persisted = state.executionOptions ?? {};\n\t\t\tconst persistedMaxIterations = persisted.maxIterations;\n\t\t\tconst callerMaxIterations = callerExecOptions.maxIterations;\n\t\t\tif (\n\t\t\t\tcallerMaxIterations !== undefined &&\n\t\t\t\tpersistedMaxIterations !== undefined &&\n\t\t\t\tcallerMaxIterations < persistedMaxIterations\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Cannot decrease maxIterations when resuming a run. Expected >= ${persistedMaxIterations}, received ${callerMaxIterations}.`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst mergedMaxIterations = callerMaxIterations ?? persistedMaxIterations;\n\t\t\tconst mergedExecOptions: ExecutionOptions & { iterationCount?: number } = {\n\t\t\t\t...callerExecOptions,\n\t\t\t\t...(mergedMaxIterations !== undefined ? { maxIterations: mergedMaxIterations } : {}),\n\t\t\t\t...(state.iterationCount !== undefined ? { iterationCount: state.iterationCount } : {}),\n\t\t\t};\n\n\t\t\tconst resumeOptions: RuntimeExecutionOptions = {\n\t\t\t\tpersistence: state.persistence,\n\t\t\t\t...mergedExecOptions,\n\t\t\t};\n\n\t\t\tconst claimed = await this.runState.claimResume(this.runId, state);\n\t\t\tif (!claimed) {","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/runtime/loop/agent-runtime.ts#L389-L425","documentation":"Thrown by the max-nodes validator when the number of instances of a single node type exceeds the maxNodes limit declared in that node type's description. Several n8n node types are singletons (e.g. one Schedule Trigger per workflow) and declare maxNodes=1; exceeding it is a structural error.","triggerScenarios":"After grouping nodes by type (count > 1), the validator resolves the first instance's version, looks up nodeType.description.maxNodes via the nodeTypesProvider, and fires when count > maxNodes. Only types that actually declare a numeric maxNodes are constrained.","commonSituations":"Adding a second Schedule Trigger or other singleton node; merging two workflows that each contained the same limited node type; an AI builder duplicating a trigger because it misread the requirement.","solutions":["Remove the extra instance(s) of the node type until count is within maxNodes.","If you genuinely need parallel schedules or branches, restructure to use a single trigger feeding into a branch/merge instead of duplicate singleton nodes.","Confirm the node type's maxNodes value via its description if you believe the limit is wrong."],"exampleFix":"// before — two Schedule Trigger nodes in one workflow\nscheduleTrigger({ name: 'Every Hour' });\nscheduleTrigger({ name: 'Every Day' });\n\n// after — one trigger, branch with a Switch/IF on time\nconst trigger = scheduleTrigger({ name: 'Run' });\n// route to hourly vs daily logic downstream","handlingStrategy":"validation","validationCode":"function countByType(nodes: Array<{ type: string }>): Map<string, number> {\n  const m = new Map<string, number>();\n  for (const n of nodes) m.set(n.type, (m.get(n.type) ?? 0) + 1);\n  return m;\n}\n\n// before validating, check against each node type's maxNodes:\nfor (const [type, count] of countByType(allNodes)) {\n  const max = nodeTypesProvider.getByNameAndVersion(type, version)?.description?.maxNodes;\n  if (max !== undefined && count > max) throw new Error(`${type}: ${count} exceeds maxNodes ${max}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Track singleton node types in your generator and refuse to emit a second instance.","When merging workflows, dedupe singleton trigger types first.","Read maxNodes from the node description rather than hardcoding assumptions."],"tags":["workflow-structure","node-limits","validation"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}