alibaba/spring-ai-alibaba · error · IllegalArgumentException

Unknown agent status code:

Error message

Unknown agent status code: 

What it means

AgentStatus.fromCode maps a string status code to the AgentStatus enum by scanning values(); if no constant matches, it throws IllegalArgumentException. It is a strict code-to-enum translation guard for agent status values.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/runtime/enums/agent/AgentStatus.java:54

	ERROR("error");

	private final String code;

	AgentStatus(String code) {
		this.code = code;
	}

	public String getCode() {
		return code;
	}

	public static AgentStatus fromCode(String code) {
		for (AgentStatus status : values()) {
			if (status.getCode().equals(code)) {
				return status;
			}
		}
		throw new IllegalArgumentException("Unknown agent status code: " + code);
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Log and inspect the offending code string and compare with the valid values() codes.
2. Fix the stored/serialized value to a valid AgentStatus code.
3. Handle case/whitespace differences (code.trim().toUpperCase()) before calling fromCode.
4. Use a lenient lookup (return null or Optional) if unknown codes should be tolerated.

Example fix

// before
AgentStatus status = AgentStatus.fromCode(rawStatus);
// after
AgentStatus status = Arrays.stream(AgentStatus.values())
    .filter(s -> s.getCode().equalsIgnoreCase(rawStatus == null ? "" : rawStatus.trim()))
    .findFirst()
    .orElseThrow(() -> new IllegalArgumentException("Unknown agent status code: " + rawStatus));

// Java
boolean valid = Arrays.stream(AgentStatus.values()).anyMatch(s -> s.getCode().equals(code));
if (!valid) { log.warn("invalid agent status code: {}", code); return AgentStatus.getDefault(); }

static Optional<AgentStatus> fromCodeOrNull(String code) {
    return Arrays.stream(AgentStatus.values()).filter(s -> s.getCode().equals(code)).findFirst();
}

try { return AgentStatus.fromCode(code); } catch (IllegalArgumentException e) { log.warn("unknown agent status code: {}", code); return AgentStatus.getDefault(); }

When it happens

Trigger: Calling AgentStatus.fromCode(code) with any string that does not exactly equal one of the enum constants' getCode() values (null, typo, different casing, or a status code from an older/newer schema).

Common situations: Deserializing agent status from a database or API response that stores legacy or unknown codes; case mismatch ('DRAFT' vs 'draft'); a new status added in one version but read by an older client.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown agent type code:
• Invalid MessageType value:
• Invalid status:
• Invalid status:
• Invalid status:

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