alibaba/spring-ai-alibaba · error · IllegalArgumentException

Action must be either AsyncCommandAction or AsyncMultiComman

Error message

Action must be either AsyncCommandAction or AsyncMultiCommandAction

What it means

EdgeCondition is a record whose compact constructor validates that its action is either an AsyncCommandAction or an AsyncMultiCommandAction. Passing any other object (plain action, lambda of the wrong type, null handled separately) throws IllegalArgumentException.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/internal/edge/EdgeCondition.java:38

import java.util.Map;

import static java.lang.String.format;

/**
 * Represents a condition associated with an edge in a graph.
 * Supports both single-node routing (AsyncCommandAction) and multi-node parallel routing (AsyncMultiCommandAction).
 *
 * @param action The action to be performed asynchronously when the edge condition is met.
 *               Can be either AsyncCommandAction (single node) or AsyncMultiCommandAction (multiple nodes).
 * @param mappings A map of string key-value pairs representing additional mappings for
 * the edge condition.
 */
public record EdgeCondition(Object action, Map<String, String> mappings) {

	public EdgeCondition {
		if (action != null && !(action instanceof AsyncCommandAction) && !(action instanceof AsyncMultiCommandAction)) {
			throw new IllegalArgumentException("Action must be either AsyncCommandAction or AsyncMultiCommandAction");
		}
	}

	/**
	 * Creates an EdgeCondition with AsyncCommandAction (single node routing).
	 */
	public static EdgeCondition single(AsyncCommandAction action, Map<String, String> mappings) {
		return new EdgeCondition(action, mappings);
	}

	/**
	 * Creates an EdgeCondition with AsyncMultiCommandAction (multi-node parallel routing).
	 */
	public static EdgeCondition multi(AsyncMultiCommandAction action, Map<String, String> mappings) {
		return new EdgeCondition(action, mappings);
	}

	/**

View on GitHub (pinned to f82da0b50f)

Solutions

Wrap the action with AsyncNodeAction.makeAsync(...) / the appropriate async adapter before building the EdgeCondition.
Use EdgeCondition's provided factory methods (which produce correctly typed async actions) rather than the raw constructor.
For multi-branch routing, implement AsyncMultiCommandAction returning a Command with goto nodes.

Example fix

// before
new EdgeCondition(state -> "nodeA", mappings);
// after
new EdgeCondition(AsyncNodeAction.makeAsync(state -> "nodeA"), mappings);

Defensive patterns

Strategy: type-guard

Validate before calling

// Verify action type before constructing EdgeCondition
if (!(action instanceof AsyncCommandAction) && !(action instanceof AsyncMultiCommandAction)) {
    throw new IllegalArgumentException("wrap with makeAsync first");
}

Type guard

boolean isEdgeConditionAction(Object a) { return a instanceof AsyncCommandAction || a instanceof AsyncMultiCommandAction; }

Try / catch

try { new EdgeCondition(action, mappings); } catch (IllegalArgumentException e) { if (e.getMessage().contains("AsyncCommandAction")) { action = AsyncNodeAction.makeAsync(rawAction); } }

Prevention

Always adapt raw actions with AsyncNodeAction.makeAsync
Use EdgeCondition factory methods instead of the raw constructor
After upgrading, recheck actions previously built synchronously
Keep routing lambdas explicitly typed as async action interfaces

When it happens

Trigger: Constructing EdgeCondition directly with a non-async action object — e.g. passing a synchronous NodeAction/CommandAction or an arbitrary lambda where an AsyncCommandAction/AsyncMultiCommandAction is required.

Common situations: Custom routing edges built manually instead of via the provided factory methods (AsyncNodeAction.makeAsync etc.); refactors after upgrading from synchronous action APIs; confused generic suppliers typed as Object.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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