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.

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)

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.