alibaba/spring-ai-alibaba · error · IllegalStateException

Missing CheckpointSaver in parent graph!

Error message

Missing CheckpointSaver in parent graph!

What it means

When a subgraph (child graph) is compiled with a CheckpointSaver, the parent graph must also have one, because subgraph state must be persisted under the parent's thread. ReactAgent throws this IllegalStateException while wiring a subgraph runnable when the child compile config has a saver but the parent's compile config does not.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java:1117

					}
				}
			}
			return lastResponse;
		}

		private RunnableConfig getSubGraphRunnableConfig(RunnableConfig config) {
			RunnableConfig subGraphRunnableConfig = RunnableConfig.builder(config)
					.checkPointId(null)
					.nextNode(null)
					.addMetadata("_AGENT_", subGraphId(nodeId)) // subGraphId is the same as the name of the agent that created it
					.build();
			subGraphRunnableConfig.clearContext();
			var parentSaver = parentCompileConfig.checkpointSaver();
			var subGraphSaver = childGraph.compileConfig.checkpointSaver();

			if (subGraphSaver.isPresent()) {
				if (parentSaver.isEmpty()) {
					throw new IllegalStateException("Missing CheckpointSaver in parent graph!");
				}

				// Check saver are the same instance
				if (parentSaver.get() == subGraphSaver.get()) {
					subGraphRunnableConfig = RunnableConfig.builder(config)
							.threadId(config.threadId()
									.map(threadId -> format("%s_%s", threadId, subGraphId(nodeId)))
									.orElseGet(() -> subGraphId(nodeId)))
							.nextNode(null)
							.checkPointId(null)
							.addMetadata("_AGENT_", subGraphId(nodeId)) // subGraphId is the same as the name of the agent that created it
							.build();
					subGraphRunnableConfig.clearContext();
				}
			}
			return subGraphRunnableConfig;
		}
	}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add a CheckpointSaver to the parent graph's compile config, e.g. CompileConfig.builder().saver(new MemorySaver()).build(), so parent and child share persistence
2. Remove the CheckpointSaver from the child/sub graph's compile config if per-subgraph persistence is not required
3. Use the same saver instance for both parent and child so the equality branch is taken instead of throwing

Example fix

// before
CompileConfig parentConfig = CompileConfig.builder().build();
StateGraph parent = new StateGraph<>(...);
CompiledGraph compiled = parent.compile(parentConfig);
// after
CompileConfig parentConfig = CompileConfig.builder()
    .saver(new MemorySaver())
    .build();
CompiledGraph compiled = parent.compile(parentConfig);

if (childCompileConfig.checkpointSaver().isPresent() && parentCompileConfig.checkpointSaver().isEmpty()) {
    throw new IllegalArgumentException("Parent graph must define a CheckpointSaver when a subgraph has one");
}

When it happens

Trigger: Calling a ReactAgent (or a graph containing one) whose childGraph.compile(CompileConfig) has a checkpointSaver set, while the parent graph's compile config (parentCompileConfig) has no checkpointSaver, and subGraphRunnableConfig is being built with a cleared context.

Common situations: Adding a checkpointer to a nested/sub agent but forgetting to add one to the top-level agent or parent graph; mixing compiled subgraphs from projects where one uses MemorySaver and the parent compiles with CompileConfig.builder().build(); following old examples that compile subgraphs without a saver.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• oss ak or sk should be set.
• oss bucket should be set.
• AppNotFound
• Unsupported vector store type:
• Unknown vector store type:

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