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.

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)

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! consi
• the target for node '%s' is null!
• the node '%s' is not present as target in graph!
• AppTypeNotSupport
• unsupported format:

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