alibaba/spring-ai-alibaba · error · BizException

INVALID_PARAMS

INVALID_PARAMS

Error message

content_type

What it means

RoutingNode's apply() gives the LLM up to DEFAULT_MAX_RETRIES chances to produce a routing decision whose agent names all match configured subagents. When all retries fail, it tries createFallbackCommand(state, messages); if no fallback agent is configured, the last exception from getDecisionWithRetry is rethrown, surfacing this exhausted-retries condition as a routing failure in the graph.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/agent/BasicAgentExecutor.java:333

		if (StringUtils.isNotBlank(config.getInstructions())
				&& !MessageRole.SYSTEM.getValue().equals(chatMessages.get(0).getRole().getValue())) {
			Message message = buildInstructions(context, config.getInstructions());
			messages.add(message);
		}

		for (ChatMessage chatMessage : chatMessages) {
			Message message = null;
			switch (chatMessage.getRole()) {
				case SYSTEM -> message = buildInstructions(context, String.valueOf(chatMessage.getContent()));
				case USER -> {
					if (chatMessage.getContentType() == ContentType.TEXT) {
						message = new UserMessage(String.valueOf(chatMessage.getContent()));
					}
					else if (chatMessage.getContentType() == ContentType.MULTIMODAL) {
						message = buildMultimodelMessage(chatMessage.getContent());
					}
					else {
						throw new BizException(ErrorCode.INVALID_PARAMS.toError("content_type",
								chatMessage.getContentType().getValue() + "not supported"));
					}
				}
				case ASSISTANT -> message = new AssistantMessage(String.valueOf(chatMessage.getContent()));
			}

			messages.add(message);
		}

		return messages;
	}

	/**
	 * Builds system instructions message
	 * @param context Agent context
	 * @param instructions System instructions
	 * @return Message instance
	 */

View on GitHub (pinned to f82da0b50f)

Solutions

1. Configure a fallback agent on the RoutingAgent so exhausted retries degrade gracefully instead of throwing
2. Verify the agent names the LLM is returning match exactly the names() of registered subagents
3. Improve the routing instruction: list available agents explicitly and give examples of valid answers
4. Use a stronger/more capable model for the routing step
5. Increase DEFAULT_MAX_RETRIES if failures are marginal

Example fix

// before
RoutingAgent agent = RoutingAgent.builder()
    .name("router")
    .subAgents(List.of(plannerAgent, coderAgent))
    .model(chatModel)
    .build();
// after
RoutingAgent agent = RoutingAgent.builder()
    .name("router")
    .subAgents(List.of(plannerAgent, coderAgent))
    .model(chatModel)
    .fallbackAgent(generalAssistantAgent) // handles exhausted retries
    .build();

// before building the agent, assert every name referenced in the instruction is registered
Set<String> names = subAgents.stream().map(Agent::name).collect(java.util.stream.Collectors.toSet());
if (names.isEmpty()) throw new IllegalStateException("RoutingAgent needs at least one subagent");
if (fallbackAgent == null) log.warn("RoutingAgent has no fallback; exhausted retries will throw");

try {
    graph.invoke(inputs);
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("exhausted routing retries")) {
        // degrade: route to a default agent or requeue for human handling
        routeToDefaultAgent(inputs);
    } else { throw e; }
}

When it happens

Trigger: LLM repeatedly returns agent names that are not in the subagent list (or empty lists) for all retry attempts AND RoutingAgent was built without a fallback agent, so createFallbackCommand returns null and the underlying exception propagates from apply().

Common situations: Subagent names mismatched or renamed after the router prompt was written; LLM (or weak model) ignoring the instruction and inventing agent names; prompt/instruction ambiguity; model returning structured output that fails parsing on every attempt; deployments with no fallback configured for production robustness.

Related errors

• Invalid data format
• RoutingAgent {} attempt {}/{} returned invalid agent name: {
• code execution failed!
• ChatModel must be provided for LLM routing agent
• Failed to get valid decision after %d retries. Last invalid

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