n8n-io/n8n · error · Error

Delegated child checkpoint metadata is missing or invalid

Error message

Delegated child checkpoint metadata is missing or invalid

What it means

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.

Source

Thrown at packages/@n8n/agents/src/runtime/tools/delegate-sub-agent-tool.ts:771

			reason: ctx.cancellation.message,
		},
		createRunnerHelpers(ctx, request, options.name),
	);
}

function restoreDelegateRequest(
	input: DelegateSubAgentInput,
	ctx: ToolContext,
	continuation: JSONValue,
	policy: DelegateSubAgentPolicy | undefined,
	childPathIndexes: Map<string, number>,
): {
	checkpoint: DelegateSubAgentContinuation & { taskPath: SubAgentTaskPath };
	request: DelegateSubAgentRequest;
} {
	const checkpoint = parseDelegateSubAgentContinuation(continuation);
	if (!checkpoint) {
		throw new Error('Delegated child checkpoint metadata is missing or invalid');
	}
	if (checkpoint.subAgentId !== input.subAgentId) {
		throw new Error('Delegated child checkpoint does not match the selected sub-agent');
	}
	const { taskPath } = checkpoint;
	assertSubAgentTaskPath(taskPath);
	const key = getChildPathIndexKey(ctx);
	childPathIndexes.set(key, Math.max(childPathIndexes.get(key) ?? 0, checkpoint.childCount + 1));
	const request = createDelegateSubAgentRequest(
		input,
		ctx,
		taskPath,
		checkpoint.childCount,
		policy,
	);
	return { checkpoint: { ...checkpoint, taskPath }, request };
}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Inspect the stored continuation value in your checkpoint store to confirm it has all required fields.
2. If the continuation is unrecoverable, start a fresh delegation instead of resuming.
3. Ensure checkpoint data is not pruned or TTL-evicted before the resume is attempted.
4. Verify the library version that wrote the continuation matches the version reading it.

function isValidContinuation(c: unknown): boolean {
  return (
    typeof c === 'object' && c !== null &&
    'runId' in c && 'toolCallId' in c && 'taskPath' in c &&
    'subAgentId' in c && 'childCount' in c
  );
}
if (!isValidContinuation(storedContinuation)) {
  // do not attempt resume; start fresh
}

function isDelegateContinuation(c: unknown): c is DelegateSubAgentContinuation {
  return (
    typeof c === 'object' && c !== null &&
    typeof (c as any).runId === 'string' &&
    typeof (c as any).toolCallId === 'string' &&
    typeof (c as any).taskPath === 'string' &&
    typeof (c as any).subAgentId === 'string' &&
    typeof (c as any).childCount === 'number'
  );
}

try {
  await agent.resume(resumeData);
} catch (e) {
  if (e instanceof Error && e.message.includes('checkpoint metadata')) {
    // start a new delegation instead of resuming
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Delegated child checkpoint does not match the selected sub-a
• No pending tool call found for toolCallId: ${resumedId}
• Unknown role: ${msg.role as string}
• Run ${runId} is not suspended. Cannot resume.
• Invalid delegate sub-agent tool name "${name}": must start w

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