alibaba/spring-ai-alibaba · error

RoutingAgent attempt / returned invalid agent names

Error message

RoutingAgent {} attempt {}/{} returned invalid agent names: {}

What it means

RoutingNode.getDecisionWithRetry logs a warning when the LLM's RoutingDecision contains agent names not present among the configured sub-agents. The invalid decision is stored as lastInvalidDecision and the attempt is retried with corrective feedback.

Solutions

1. List allowed agent names explicitly in the routing prompt
2. Add schema/enum constraints on the structured output
3. Rename agents to clearer, distinct identifiers

When it happens

Trigger: Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/node/RoutingNode.java:260 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/node/RoutingNode.java:260

				List<String> decisionValues = decision.getAgentNames();

				if (decisionValues != null && !decisionValues.isEmpty()) {
					// Validate all agent names
					List<String> invalidAgents = decisionValues.stream()
							.filter(agentName -> subAgents.stream().noneMatch(agent -> agent.name().equals(agentName)))
							.collect(Collectors.toList());

					if (invalidAgents.isEmpty()) {
						if (attempt > 0) {
							logger.info("RoutingAgent {} succeeded on retry attempt {}. Routed to sub-agents: {}",
									rootAgent.name(), attempt, String.join(", ", decisionValues));
						}
						return decision;
					}
					else {
						lastInvalidDecision = decisionValues;
						logger.warn("RoutingAgent {} attempt {}/{} returned invalid agent names: {}",
								rootAgent.name(), attempt, maxRetries, invalidAgents);
					}
				}
				else {
					lastInvalidDecision = Collections.emptyList();
					logger.warn("RoutingAgent {} attempt {}/{} returned empty agent list",
							rootAgent.name(), attempt, maxRetries);
				}
			}
			catch (Exception e) {
				if (attempt == maxRetries) {
					logger.error("RoutingAgent {} failed on final attempt {}/{}", rootAgent.name(), attempt, maxRetries, e);
					throw e;
				}
				logger.warn("RoutingAgent {} attempt {}/{} encountered an error, will retry", rootAgent.name(), attempt, maxRetries, e);
			}
		}

View on GitHub (pinned to f82da0b50f)