alibaba/spring-ai-alibaba · error · IllegalStateException

Failed to add start node to queue:

Error message

Failed to add start node to queue: 

What it means

In findConvergenceNode, the BFS/fixpoint traversal that computes where parallel branches converge initializes a queue with the branch start nodes. ArrayDeque.offer() can only fail if the deque is capacity-bounded, so this IllegalStateException represents an unexpected internal invariant violation.

Solutions

1. Verify you are running an unmodified official release of spring-ai-alibaba-graph-core.
2. Report the issue with the start node ids and graph definition to the maintainers.
3. Rebuild the dependency from source to rule out a corrupted artifact.

try { graph.compile(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Failed to add start node to queue")) { /* rebuild dependency / report bug */ } }

When it happens

Trigger: queue.offer(startNode) returns false while seeding the ArrayDeque with branch start node ids — practically never happens with an unbounded ArrayDeque; it is a defensive check.

Common situations: Not reachable in normal use; if seen, it indicates a corrupted/modified library build or an exotic subclassed deque.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Failed to add nested convergence node to queue:
• Failed to add next node to queue:
• CreatePluginError
• no generator found!
• SYSTEM_ERROR

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

Appendix: source

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

		if (startNodeIds.isEmpty()) {
			return null;
		}
		if (startNodeIds.size() == 1) {
			// Single path, find its end
			String startNode = startNodeIds.iterator().next();
			return findPathEnd(startNode);
		}

		// Use BFS to find the first common node reachable from all start nodes
		// Track which start nodes can reach each node
		Map<String, Set<String>> reachableFrom = new HashMap<>();
		Deque<String> queue = new ArrayDeque<>();

		// Initialize: mark each start node as reachable from itself
		for (String startNode : startNodeIds) {
			reachableFrom.put(startNode, new HashSet<>(Set.of(startNode)));
			if (!queue.offer(startNode)) {
				throw new IllegalStateException("Failed to add start node to queue: " + startNode);
			}
		}

		while (!queue.isEmpty()) {
			String current = queue.poll();
			Set<String> sources = reachableFrom.get(current);
			if (sources == null) {
				continue;
			}

			// Get next nodes from current node
			Optional<Edge> edgeOpt = processedData.edges().edgeBySourceId(current);
			if (edgeOpt.isEmpty()) {
				// No outgoing edge - this could be an end point
				// Check if all paths reach here
				if (sources.size() == startNodeIds.size()) {
					return current;
				}

View on GitHub (pinned to f82da0b50f)