alibaba/spring-ai-alibaba · error · RuntimeException

Failed to create subgraph action for path starting at:

Error message

Failed to create subgraph action for path starting at: 

What it means

When compiling advanced parallel edges, ParallelEdgeProcessor builds a subgraph action for each path via subGraphNode.actionFactory().apply(compileConfig). If the action factory raises a GraphStateException, it is rethrown as a RuntimeException with this message and the starting node id of the path.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/internal/ParallelEdgeProcessor.java:216

			List<AsyncNodeActionWithConfig> subGraphActions = new ArrayList<>();
			List<String> subGraphNodeIds = new ArrayList<>();

			for (ParallelPath path : paths) {
				// Create subgraph for this single path
				StateGraph subStateGraph = createSubgraphForPath(path);

				// Compile the subgraph into CompiledGraph
				CompiledGraph subCompiledGraph = subStateGraph.compile(compileConfig);

				// Create SubCompiledGraphNode for this path
				String subGraphNodeId = format("__PARALLEL_SUBGRAPH__(%s->%s)", sourceNodeId, path.startNodeId);
				var subGraphNode = new SubCompiledGraphNode(subGraphNodeId, subCompiledGraph);

				// Collect actions and node IDs for ParallelNode
				try {
					subGraphActions.add(subGraphNode.actionFactory().apply(compileConfig));
				} catch (GraphStateException ex) {
					throw new RuntimeException("Failed to create subgraph action for path starting at: "
							+ path.startNodeId + ". Cause: " + ex.getMessage(), ex);
				}
				subGraphNodeIds.add(subGraphNodeId);
			}

			// Create a ParallelNode that executes all subgraphs in parallel
			var parallelNode = new ParallelNode(sourceNodeId, convergenceNodeId, subGraphActions, subGraphNodeIds,
					keyStrategyMap, compileConfig);

			nodeFactoriesUpdater.accept(parallelNode.id(), parallelNode.actionFactory());
			edgesUpdater.accept(sourceNodeId, new EdgeValue(parallelNode.id()));
			edgesUpdater.accept(parallelNode.id(), new EdgeValue(convergenceNodeId));
		} else {
			// Simple case: A->B->Z, A->C->Z - use ParallelNode
			var targetList = validTargets;

			var actions = targetList.stream()
					.map(target -> {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Read the wrapped GraphStateException cause for the exact subgraph node/validation error.
2. Check that every path starting at the reported startNodeId targets nodes that exist in the compiled graph.
3. Validate edge definitions (Edges/EdgesEnum) for the parallel branch before compiling.
4. Ensure the CompileConfig passed to the action factory matches the subgraph's requirements (saver, recursion limit).

Example fix

// before: branch routes to undefined node
.addEdge("fork", EdgesEnum.to("analizer"));
// after: correct node id
.addEdge("fork", EdgesEnum.to("analyzer"));

// Validate branch targets before compiling the StateGraph
for (String targetId : branchTargetIds) {
    if (!graph.nodes().containsKey(targetId)) throw new IllegalStateException("Undefined node: " + targetId);
}

try { compiled = graph.compile(config); } catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to create subgraph action")) { /* fix branch defined at reported startNodeId */ } }

When it happens

Trigger: An async action factory for a subgraph node invoked with the current CompileConfig throws GraphStateException — typically a node in the subgraph references a missing node id, an invalid edge, or an unresolvable condition mapping during action creation.

Common situations: See trigger scenarios.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Failed to create parallel node action for target:
• Missing CheckpointSaver in parent graph!
• subgraph not support start with parallel branches yet!
• the target for node '%s' is null!
• the node '%s' is not present as target in graph!

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