n8n-io/n8n · error

SUBNODE_NOT_CONNECTED

SUBNODE_NOT_CONNECTED

Error message

${nodeRef} is a subnode that must be connected to a parent node as ${subnodeInfo.subnodeField}, but it has no such connection. Use the appropriate subnode factory (e.g., embedding(), languageModel()) and connect it to a parent node's subnodes config.

What it means

Error "${nodeRef} is a subnode that must be connected to a parent node as ${subnodeInfo.subnodeField}, but it has no such connection. Use the appropriate subnode factory (e.g., embedding(), languageModel()) and connect it to a parent node's subnodes config." thrown in n8n-io/n8n.

Solutions

1. Create the subnode with its factory (e.g. embedding(), languageModel()) and pass it to the parent node's subnodes config so the AI connection is created
2. Check that the parent node type expects this subnode type (subnodeInfo.connectionType)
3. Do not build the subnode as a standalone node; it must be wired to a parent to appear in the workflow

When it happens

Trigger: Thrown at packages/@n8n/workflow-sdk/src/workflow-builder/plugins/validators/subnode-connection-validator.ts:108 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at packages/@n8n/workflow-sdk/src/workflow-builder/plugins/validators/subnode-connection-validator.ts:108

	// Per-node validation not used - we do workflow-level validation
	validateNode: () => [],

	validateWorkflow(ctx: PluginContext): ValidationIssue[] {
		const issues: ValidationIssue[] = [];

		for (const [mapKey, graphNode] of ctx.nodes) {
			const subnodeInfo = getRequiredSubnodeInfo(graphNode.instance.type);
			if (subnodeInfo) {
				// This is a subnode-only type - verify it has the required AI connection
				if (!hasAiConnectionOfType(graphNode, subnodeInfo.connectionType)) {
					const originalName = graphNode.instance.name;
					const renamed = isAutoRenamed(mapKey, originalName);
					const displayName = renamed ? mapKey : originalName;
					const origForDisplay = renamed ? originalName : undefined;
					const nodeRef = formatNodeRef(displayName, origForDisplay, graphNode.instance.type);

					issues.push({
						code: 'SUBNODE_NOT_CONNECTED',
						message: `${nodeRef} is a subnode that must be connected to a parent node as ${subnodeInfo.subnodeField}, but it has no such connection. Use the appropriate subnode factory (e.g., embedding(), languageModel()) and connect it to a parent node's subnodes config.`,
						severity: 'error',
						nodeName: displayName,
						originalName: origForDisplay,
					});
				}
			}
		}

		return issues;
	},
};

View on GitHub (pinned to 5ac6606e81)