n8n-io/n8n · error · Error

Subnode error handling is managed by parent node SubnodeConf

Error message

Subnode error handling is managed by parent node SubnodeConfig

What it means

Thrown by SubnodeInstanceImpl.onError() — error-handling wiring (.onError(handler)) is owned by the parent SubnodeConfig node. A subnode cannot independently declare an error handler, so attempting to attach one throws.

Source

Thrown at packages/@n8n/workflow-sdk/src/workflow-builder/node-builders/subnode-builders.ts:153

		throw new Error('Subnode output connections are managed by parent node SubnodeConfig');
	}

	then<T extends NodeInstance<string, string, unknown>>(
		_target: T | T[] | InputTarget,
		_outputIndex?: number,
	): NodeChain<NodeInstance<TType, TVersion, TOutput>, T> {
		throw new Error('Subnode connections are managed by parent node SubnodeConfig');
	}

	to<T extends NodeInstance<string, string, unknown>>(
		_target: T | T[] | InputTarget,
		_outputIndex?: number,
	): NodeChain<NodeInstance<TType, TVersion, TOutput>, T> {
		throw new Error('Subnode connections are managed by parent node SubnodeConfig');
	}

	onError<T extends NodeInstance<string, string, unknown>>(_handler: T): this {
		throw new Error('Subnode error handling is managed by parent node SubnodeConfig');
	}

	getConnections(): DeclaredConnection[] {
		return [];
	}
}

// =============================================================================
// Factory Functions
// =============================================================================

/**
 * Create a language model subnode instance.
 *
 * Use this for nodes that output `ai_languageModel` connection type,
 * such as OpenAI Chat Model, Anthropic, Google Gemini, etc.
 *
 * @example

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Attach the error handler to the parent SubnodeConfig via .onError().
2. Guard the loop with a SubnodeInstanceImpl check before calling .onError().
3. Model error handling at the agent level rather than per-tool.

Example fix

// before
toolNode.onError(errorHandler); // throws
// after
agent.onError(errorHandler);

if (!(node instanceof SubnodeInstanceImpl)) {
  node.onError(handler);
}

function isSubnodeInstance(n: unknown): n is SubnodeInstanceImpl {
  return n instanceof SubnodeInstanceImpl;
}

When it happens

Trigger: Calling toolNode.onError(errorHandlerNode) when wiring up an AI tool; a generic post-processing pass that attaches error handlers to every node.

Common situations: Adding fault-tolerance to a workflow that includes tools; copying a pattern from a top-level node onto a subnode.

Related errors

• Subnode input connections are managed by parent node Subnode
• Subnode output connections are managed by parent node Subnod
• Subnode connections are managed by parent node SubnodeConfig
• Nodes from fromJSON() do not support onError()
• Reflector output must be valid JSON

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