n8n-io/n8n · error · UserError

Human-in-the-Loop nodes cannot be used inside a sub-agent. M

Error message

Human-in-the-Loop nodes cannot be used inside a sub-agent. Move "${action.nodeName}" to the top-level workflow.

What it means

Thrown by assertNoHitlActions when a sub-agent (Agent Tool V3 running inside a top-level agent) receives an action whose metadata.hitl flag is set. HITL approval nodes rely on the top-level execution engine, which is not available inside a tool-callback sub-agent context, so they are rejected upfront with a clear UserError. The description notes that the sub-agent step is aborted and sibling tool calls are skipped.

Source

Thrown at packages/@n8n/nodes-langchain/nodes/agents/Agent/agents/ToolsAgent/V3/helpers/resolveSubAgentRequest.ts:52

	while (isEngineRequest(current)) {
		assertNoHitlActions(node, current.actions);
		ctx.getExecutionCancelSignal?.()?.throwIfAborted?.();

		const actionResponses = await Promise.all(
			current.actions.map(async (action) => await executeEngineAction(node, action, tools)),
		);

		current = await deps.runAgentBatch({ actionResponses, metadata: current.metadata });
	}

	return current;
}

function assertNoHitlActions(node: INode, actions: Action[]): void {
	for (const action of actions) {
		if (action.metadata?.hitl) {
			throw new UserError(
				`Human-in-the-Loop nodes cannot be used inside a sub-agent. Move "${action.nodeName}" to the top-level workflow.`,
				{
					description:
						'Approval flows need the top-level engine; the sub-agent step is aborted (sibling tool calls skipped).',
					extra: { node: node.name },
				},
			);
		}
	}
}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Move the HITL (Wait for Approval) node out of the sub-agent and into the top-level workflow.
2. Replace the HITL node inside the sub-agent with a non-blocking alternative (e.g. auto-approve, or return a default response).
3. Redesign so the sub-agent returns a value and the top-level workflow performs the approval.

// Authoring-time validation: scan the sub-agent workflow for HITL nodes before registering it
const hitlNodes = subWorkflow.nodes.filter(n => n.type.includes('hitl') || n.type.includes('approval'));
if (hitlNodes.length > 0) {
  throw new UserError('Sub-agent workflow contains HITL nodes — move them to the top-level workflow.');
}

function isHitlAction(action: Action): boolean {
  return !!action.metadata?.hitl;
}

When it happens

Trigger: An Agent Tool (sub-agent) workflow contains a Wait for Approval / HITL node. The top-level engine routes its actions through resolveSubAgentRequest, which detects the hitl flag and refuses.

Common situations: User nested an approval flow inside an Agent Tool expecting it to block; refactored a top-level workflow into a sub-agent without removing the HITL node; copied an approval step into the wrong canvas.

Related errors

• Please connect a model to the Fallback Model input or disabl
• Max iterations (${maxIterations}) reached. The agent could n
• The "text" parameter is empty.
• The “text” parameter is empty.
• This model is not supported in ${version} version of the Age

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