{"record":{"id":"c396688acb3ca006","repo":"n8n-io/n8n","slug":"subnode-connections-are-managed-by-parent-node-sub","errorCode":null,"errorMessage":"Subnode connections are managed by parent node SubnodeConfig","messagePattern":"Subnode connections are managed by parent node SubnodeConfig","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/workflow-sdk/src/workflow-builder/node-builders/subnode-builders.ts","lineNumber":142,"sourceCode":"\t\t\tthis._subnodeType,\n\t\t\tthis.id,\n\t\t\tthis.name,\n\t\t);\n\t}\n\n\tinput(_index: number): InputTarget {\n\t\tthrow new Error('Subnode input connections are managed by parent node SubnodeConfig');\n\t}\n\n\toutput(_index: number): OutputSelector<TType, TVersion, TOutput> {\n\t\tthrow new Error('Subnode output connections are managed by parent node SubnodeConfig');\n\t}\n\n\tthen<T extends NodeInstance<string, string, unknown>>(\n\t\t_target: T | T[] | InputTarget,\n\t\t_outputIndex?: number,\n\t): NodeChain<NodeInstance<TType, TVersion, TOutput>, T> {\n\t\tthrow new Error('Subnode connections are managed by parent node SubnodeConfig');\n\t}\n\n\tto<T extends NodeInstance<string, string, unknown>>(\n\t\t_target: T | T[] | InputTarget,\n\t\t_outputIndex?: number,\n\t): NodeChain<NodeInstance<TType, TVersion, TOutput>, T> {\n\t\tthrow new Error('Subnode connections are managed by parent node SubnodeConfig');\n\t}\n\n\tonError<T extends NodeInstance<string, string, unknown>>(_handler: T): this {\n\t\tthrow new Error('Subnode error handling is managed by parent node SubnodeConfig');\n\t}\n\n\tgetConnections(): DeclaredConnection[] {\n\t\treturn [];\n\t}\n}\n","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/workflow-sdk/src/workflow-builder/node-builders/subnode-builders.ts#L124-L160","documentation":"Thrown by SubnodeInstanceImpl.then() — the fluent .then(target) chaining method is disabled for subnodes because their connection graph is controlled by the parent SubnodeConfig. Calling .then() on a subnode attempts to create a connection that the parent must own, so it is rejected at runtime.","triggerScenarios":"Writing toolNode.then(otherNode) as if the tool were a standalone node; using a generic pipeline helper that chains all nodes via .then().","commonSituations":"Porting a linear chain pattern to a graph that includes AI tools; auto-generating builder code that calls .then() uniformly.","solutions":["Move the .then(...) call to the parent SubnodeConfig node.","Skip subnodes in any generic chaining utility via a SubnodeInstanceImpl type guard.","Use .to() on the parent for successor wiring instead of chaining off the subnode."],"exampleFix":"// before\ntoolNode.then(downstream); // throws\n// after\nagent.then(downstream); // parent SubnodeConfig owns it","handlingStrategy":"type-guard","validationCode":"if (!(node instanceof SubnodeInstanceImpl)) {\n  node.then(target);\n}","typeGuard":"function isSubnodeInstance(n: unknown): n is SubnodeInstanceImpl {\n  return n instanceof SubnodeInstanceImpl;\n}","tryCatchPattern":null,"preventionTips":["Chain off the parent SubnodeConfig, not subnodes.","Guard generic chaining helpers with an instanceof check.","Keep subnodes inside their parent's builder scope."],"tags":["subnode","connections","workflow-builder","fluent-api","chaining"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}