alibaba/spring-ai-alibaba · error · GraphStateException

subgraph not support start with parallel branches yet!

Error message

subgraph not support start with parallel branches yet!

What it means

When a node wraps a subgraph, ProcessedNodesEdgesAndConfig.process validates the subgraph's structure. If the subgraph's START edge is a parallel (fan-out) edge, a GraphStateException is thrown because subgraph entry with parallel branches is not supported.

Source

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

			var sgWorkflow = subgraphNode.subGraph();

            // Merges keyStrategies of this subgraph.
            subgraphNode.keyStrategies().forEach(keyStrategyMap::putIfAbsent);
            // Merges the keyStrategyMap aggregated from recursive subgraphs.
            ProcessedNodesEdgesAndConfig processedSubGraph = process(sgWorkflow, config);
            processedSubGraph.keyStrategyMap().forEach(keyStrategyMap::putIfAbsent);

			StateGraph.Nodes processedSubGraphNodes = processedSubGraph.nodes;
			StateGraph.Edges processedSubGraphEdges = processedSubGraph.edges;

			//
			// Process START Node
			//
			var sgEdgeStart = processedSubGraphEdges.edgeBySourceId(START).orElseThrow();

			if (sgEdgeStart.isParallel()) {
				throw new GraphStateException("subgraph not support start with parallel branches yet!");
			}

			var sgEdgeStartTarget = sgEdgeStart.target();

			if (sgEdgeStartTarget.id() == null) {
				throw new GraphStateException(format("the target for node '%s' is null!", subgraphNode.id()));
			}

			var sgEdgeStartRealTargetId = subgraphNode.formatId(sgEdgeStartTarget.id());

			// Process Interruption (Before) Subgraph(s)
			interruptsBefore = interruptsBefore.stream()
					.map(interrupt -> Objects.equals(subgraphNode.id(), interrupt) ? sgEdgeStartRealTargetId
							: interrupt)
					.collect(Collectors.toUnmodifiableSet());

			var edgesWithSubgraphTargetId = edges.edgesByTargetId(subgraphNode.id());

View on GitHub (pinned to f82da0b50f)

Solutions

1. Introduce a single-entry dispatcher node: START -> dispatcher, then branch from dispatcher with parallel edges.
2. Keep parallel fan-out out of the subgraph's START edge; move branching after the first node.
3. Inline the parallel nodes into the parent graph instead of embedding as a subgraph.

Example fix

// before
subGraph.addEdge(START, "a", "b"); // parallel from START
parent.addNode("sub", subGraph);
// after
subGraph.addEdge(START, "entry");
subGraph.addParallelBranch(List.of("a", "b"), "entry");
parent.addNode("sub", subGraph);

Edge sgEdgeStart = subCompiled.getGraph().edgeBySourceId(START).orElseThrow(); if (sgEdgeStart.isParallel()) throw new IllegalStateException("Subgraph must not start with parallel branches");

try { parent.addNode("sub", subGraph); compiled = parent.compile(cfg); } catch (GraphStateException e) { log.error("Subgraph structure unsupported: {}", e.getMessage()); }

When it happens

Trigger: Adding a node via addNode(id, subGraph) where subGraph's START connects through addConditionalEdges/addParallelBranches (parallel fan-out from START).

Common situations: Reusing a top-level workflow as a subgraph when that workflow starts with a parallel fan-out; refactoring a graph's start into parallel branches and embedding it elsewhere.

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

• Missing CheckpointSaver in parent graph!
• recursionLimit must be > 0!
• Conditional multi-command mapping from node '
• Failed to create parallel node action for target:
• the target for node '%s' is null!

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