{"record":{"id":"e179596b79933bc1","repo":"n8n-io/n8n","slug":"delegated-child-checkpoint-metadata-is-missing-or","errorCode":null,"errorMessage":"Delegated child checkpoint metadata is missing or invalid","messagePattern":"Delegated child checkpoint metadata is missing or invalid","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/runtime/tools/delegate-sub-agent-tool.ts","lineNumber":771,"sourceCode":"\t\t\treason: ctx.cancellation.message,\n\t\t},\n\t\tcreateRunnerHelpers(ctx, request, options.name),\n\t);\n}\n\nfunction restoreDelegateRequest(\n\tinput: DelegateSubAgentInput,\n\tctx: ToolContext,\n\tcontinuation: JSONValue,\n\tpolicy: DelegateSubAgentPolicy | undefined,\n\tchildPathIndexes: Map<string, number>,\n): {\n\tcheckpoint: DelegateSubAgentContinuation & { taskPath: SubAgentTaskPath };\n\trequest: DelegateSubAgentRequest;\n} {\n\tconst checkpoint = parseDelegateSubAgentContinuation(continuation);\n\tif (!checkpoint) {\n\t\tthrow new Error('Delegated child checkpoint metadata is missing or invalid');\n\t}\n\tif (checkpoint.subAgentId !== input.subAgentId) {\n\t\tthrow new Error('Delegated child checkpoint does not match the selected sub-agent');\n\t}\n\tconst { taskPath } = checkpoint;\n\tassertSubAgentTaskPath(taskPath);\n\tconst key = getChildPathIndexKey(ctx);\n\tchildPathIndexes.set(key, Math.max(childPathIndexes.get(key) ?? 0, checkpoint.childCount + 1));\n\tconst request = createDelegateSubAgentRequest(\n\t\tinput,\n\t\tctx,\n\t\ttaskPath,\n\t\tcheckpoint.childCount,\n\t\tpolicy,\n\t);\n\treturn { checkpoint: { ...checkpoint, taskPath }, request };\n}\n","sourceCodeStart":753,"sourceCodeEnd":789,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/runtime/tools/delegate-sub-agent-tool.ts#L753-L789","documentation":"Thrown by restoreDelegateRequest when parseDelegateSubAgentContinuation(continuation) returns a falsy value. The continuation is the checkpoint metadata stored when a delegated child suspended. If it is missing, null, or does not match the expected shape, the library cannot reconstruct the child's execution context and refuses to resume.","triggerScenarios":"Resuming a suspended delegate tool call where the stored continuation JSON is null, an empty object, missing required fields (runId, toolCallId, taskPath, subAgentId, childCount), or has been corrupted in storage. Also triggered if the checkpoint store returned a continuation from a different tool version.","commonSituations":"Database schema migration that dropped or renamed continuation columns. Checkpoint store returning null after data expiration or eviction. Version mismatch between the agent that suspended and the one resuming (continuation shape changed between releases).","solutions":["Inspect the stored continuation value in your checkpoint store to confirm it has all required fields.","If the continuation is unrecoverable, start a fresh delegation instead of resuming.","Ensure checkpoint data is not pruned or TTL-evicted before the resume is attempted.","Verify the library version that wrote the continuation matches the version reading it."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"function isValidContinuation(c: unknown): boolean {\n  return (\n    typeof c === 'object' && c !== null &&\n    'runId' in c && 'toolCallId' in c && 'taskPath' in c &&\n    'subAgentId' in c && 'childCount' in c\n  );\n}\nif (!isValidContinuation(storedContinuation)) {\n  // do not attempt resume; start fresh\n}","typeGuard":"function isDelegateContinuation(c: unknown): c is DelegateSubAgentContinuation {\n  return (\n    typeof c === 'object' && c !== null &&\n    typeof (c as any).runId === 'string' &&\n    typeof (c as any).toolCallId === 'string' &&\n    typeof (c as any).taskPath === 'string' &&\n    typeof (c as any).subAgentId === 'string' &&\n    typeof (c as any).childCount === 'number'\n  );\n}","tryCatchPattern":"try {\n  await agent.resume(resumeData);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('checkpoint metadata')) {\n    // start a new delegation instead of resuming\n  } else throw e;\n}","preventionTips":["Verify checkpoint store data integrity before attempting resume.","Ensure library versions are consistent between suspend and resume.","Do not manually edit or migrate checkpoint continuation blobs without schema validation."],"tags":["checkpoint","resume","delegate-tool","data-integrity"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}