alibaba/spring-ai-alibaba · error · IllegalStateException

Cannot convert MultiCommand with multiple nodes to Command

Error message

Cannot convert MultiCommand with multiple nodes to Command

What it means

MultiCommand.toCommand() converts a MultiCommand to a single-target Command, which is only possible when exactly one goto node is present. With multiple goto nodes the conversion is ambiguous, so an IllegalStateException is thrown.

Solutions

1. Call isSingleNode() before toCommand() and handle multi-target commands with the multi-node execution path
2. Use gotoNodes.get(0) explicitly only when discarding extra targets is intentional
3. Refactor the node to return Command when it only ever targets one node
4. Inspect the router logic if a single-target route unexpectedly returns multiple nodes

Example fix

// before
Command cmd = multiCommand.toCommand(); // throws for multiple nodes
// after
Command cmd = multiCommand.isSingleNode()
        ? multiCommand.toCommand()
        : handleMultiTarget(multiCommand);

if (!multiCommand.isSingleNode()) { /* route via multi-node path */ }

static Optional<Command> asSingleCommand(MultiCommand mc) {
    return mc.isSingleNode() ? Optional.of(mc.toCommand()) : Optional.empty();
}

try { cmd = mc.toCommand(); } catch (IllegalStateException e) { cmd = handleMulti(mc); }

When it happens

Trigger: Calling multiCommand.toCommand() on a MultiCommand constructed with two or more goto nodes (isSingleNode() returns false).

Common situations: Generic code paths that normalize any node result via toCommand() without checking multi-node commands; refactors where a previously single-target route started returning multiple branches.

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

• Cannot merge incompatible types
• gotoNodes cannot be empty
• No default output or error next node provided
• Action must be either AsyncCommandAction or…
• AgentScope routing flow requires agentScopeModel in config…

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/action/MultiCommand.java:63

		this(gotoNodes, Map.of());
	}

	/**
	 * Checks if this MultiCommand represents a single node (for backward compatibility).
	 * @return true if there's only one node, false otherwise
	 */
	public boolean isSingleNode() {
		return gotoNodes.size() == 1;
	}

	/**
	 * Converts a single-node MultiCommand to a regular Command.
	 * @return a Command instance if this is a single node, otherwise throws an exception
	 * @throws IllegalStateException if this MultiCommand contains multiple nodes
	 */
	public Command toCommand() {
		if (!isSingleNode()) {
			throw new IllegalStateException("Cannot convert MultiCommand with multiple nodes to Command");
		}
		return new Command(gotoNodes.get(0), update);
	}
}

View on GitHub (pinned to f82da0b50f)