alibaba/spring-ai-alibaba · error · IllegalArgumentException

Unknown agent type code:

Error message

Unknown agent type code: 

What it means

AgentType.fromCode maps a string type code to the AgentType enum by scanning values(); if nothing matches it throws IllegalArgumentException. It enforces that only known agent type codes are accepted.

Solutions

1. Print valid codes (Arrays.toString(AgentType.values())) and correct the input to one of them.
2. Normalize input (trim/case) before the lookup.
3. Migrate stored data containing stale type codes to current enum codes.
4. Fall back to a default type or Optional-based lookup if unknown types are expected.

Example fix

// before
AgentType type = AgentType.fromCode(dto.getType());
// after
AgentType type = Optional.ofNullable(AgentType.fromCodeOrNull(dto.getType()))
    .orElseThrow(() -> new IllegalArgumentException("Unsupported agent type: " + dto.getType()));

// Java
boolean valid = Arrays.stream(AgentType.values()).anyMatch(t -> t.getCode().equals(typeCode));
if (!valid) throw new IllegalArgumentException("Unsupported agent type: " + typeCode);

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

try { return AgentType.fromCode(typeCode); } catch (IllegalArgumentException e) { log.warn("unknown agent type code: {}", typeCode); return AgentType.defaultType(); }

When it happens

Trigger: Calling AgentType.fromCode(code) with a string not matching any enum constant's getCode() — e.g. a misspelled type, wrong casing, or a type code written by a newer/older schema version.

Common situations: Persisting agent type as a raw string in DB/API payloads and reading it back after a rename or upgrade; frontend sending a type label instead of the canonical code.

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 status 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/b2070ee75297cec1. Report an issue: GitHub.

Appendix: source

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

	private final String code;

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

	@JsonValue
	public String getCode() {
		return code;
	}

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

}

View on GitHub (pinned to f82da0b50f)