alibaba/spring-ai-alibaba · error · GraphStateException

subgraph not support routes to parallel branches yet!

Error message

subgraph not support routes to parallel branches yet!

What it means

After processing a subgraph's END edges, the library needs to route the subgraph node's outgoing edge in the parent graph. Parallel (branching) outgoing edges from a subgraph node are not supported, so process() throws this GraphStateException.

Solutions

1. Insert an intermediate regular node after the subgraph and make that node the source of the parallel branches
2. Use a conditional edge with a router action after the subgraph instead of a parallel edge
3. Restructure so parallelism happens inside the subgraph, not immediately after it
4. Check the framework version/release notes for updated subgraph parallel support

Example fix

// before
outer.addEdge("sub", List.of("a", "b"));
// after
outer.addNode("fanout", state -> Map.of());
outer.addEdge("sub", "fanout");
outer.addEdge("fanout", List.of("a", "b"));

var e = parent.edges.edgeBySourceId("sub").orElseThrow();
if (e.isParallel()) throw new IllegalStateException("insert an intermediate node before fanning out from a subgraph");

try { outer.compile(saver); } catch (GraphStateException ex) { if (ex.getMessage().contains("routes to parallel branches")) { /* restructure with intermediate node */ } else throw ex; }

When it happens

Trigger: Parent graph defines a parallel branch originating from a subgraph node, e.g. addEdges("sub", List.of("a","b")) or an edge with multiple targets whose source is the subgraph node, then compiling the parent.

Common situations: Fan-out patterns where developers want one subgraph result to feed several parallel nodes; usually fixed by inserting an intermediate router/regular node between the subgraph and the branches.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• 'interruption after' on subgraph is not supported yet!…
• the node ' ' is not present as target in graph!
• the target for node ' ' is null!
• AppTypeNotSupport
• Cannot convert MultiCommand with multiple nodes to Command

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/f834b746e7a37adc. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/ProcessedNodesEdgesAndConfig.java:132

			for (var edgeWithSubgraphTargetId : edgesWithSubgraphTargetId) {

				var newEdge = edgeWithSubgraphTargetId.withSourceAndTargetIdsUpdated(subgraphNode, Function.identity(),
						id -> new EdgeValue((Objects.equals(id, subgraphNode.id())
								? subgraphNode.formatId(sgEdgeStartTarget.id())
								: id)));
				edges.elements.remove(edgeWithSubgraphTargetId);
				edges.elements.add(newEdge);
			}
			//
			// Process END Nodes
			//
			var sgEdgesEnd = processedSubGraphEdges.edgesByTargetId(END);

			var edgeWithSubgraphSourceId = edges.edgeBySourceId(subgraphNode.id()).orElseThrow();

			if (edgeWithSubgraphSourceId.isParallel()) {
				throw new GraphStateException("subgraph not support routes to parallel branches yet!");
			}

			// Process Interruption (After) Subgraph(s)
			if (interruptsAfter.contains(subgraphNode.id())) {

				var exceptionMessage = (edgeWithSubgraphSourceId.target()
						.id() == null) ? "'interruption after' on subgraph is not supported yet!"
								: format(
										"'interruption after' on subgraph is not supported yet! consider to use 'interruption before' node: '%s'",
										edgeWithSubgraphSourceId.target().id());
				throw new GraphStateException(exceptionMessage);
			}

			sgEdgesEnd.stream()
					.map(e -> e.withSourceAndTargetIdsUpdated(subgraphNode, subgraphNode::formatId,
							id -> (Objects.equals(id, END) ? edgeWithSubgraphSourceId.target()
									: new EdgeValue(subgraphNode.formatId(id)))))
					.forEach(edges.elements::add);

View on GitHub (pinned to f82da0b50f)