alibaba/spring-ai-alibaba · error · IllegalArgumentException

Invalid MessageType value:

Error message

Invalid MessageType value: 

What it means

MessageRole.of() iterates all MessageRole enum constants and throws IllegalArgumentException when no constant's value equals the given string. This means an unrecognized message role string (after the trailing value in the message) was passed, e.g. from deserialized chat data. It is a fail-fast guard for the OPEN/ASSISTANT/... role vocabulary of the chat protocol.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-runtime/src/main/java/com/alibaba/cloud/ai/studio/runtime/domain/chat/MessageRole.java:67

	MessageRole(String value) {
		this.value = value;
	}

	/**
	 * Converts a string value to its corresponding MessageRole enum.
	 * @param value The string value to convert
	 * @return The corresponding MessageRole enum
	 * @throws IllegalArgumentException if the value is invalid
	 */
	public static MessageRole of(String value) {
		for (MessageRole messageRole : MessageRole.values()) {
			if (messageRole.getValue().equals(value)) {
				return messageRole;
			}
		}

		throw new IllegalArgumentException("Invalid MessageType value: " + value);
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Use only the role strings defined by MessageRole values (check the enum's getValue() strings).
2. Normalize/trim the input string before calling of().
3. Wrap of() in try-catch (IllegalArgumentException) if the role comes from external data, and default to a safe role.
4. If a new role is genuinely needed, add a constant to MessageRole instead of passing an ad-hoc string.

Example fix

// before
MessageRole role = MessageRole.of("bot"); // throws
// after
MessageRole role = MessageRole.of("assistant"); // or validate first
if (role == null) { role = MessageRole.USER; }

boolean knownRole = Arrays.stream(MessageRole.values())
    .anyMatch(r -> r.getValue().equals(input));

MessageRole safeRole(String v) {
  try { return MessageRole.of(v); }
  catch (IllegalArgumentException e) { return MessageRole.USER; }
}

try {
  role = MessageRole.of(value);
} catch (IllegalArgumentException e) {
  log.warn("Unknown message role: {}", value);
  role = MessageRole.USER;
}

When it happens

Trigger: Calling MessageRole.of(value) with a string that is not any enum constant's value, including null or empty string.

Common situations: Deserializing chat messages persisted by an older/newer version whose role strings differ; API clients sending unknown roles like "function" or "tool"; passing raw model output directly as a role.

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:
• Unknown agent type code:
• Invalid status:
• Invalid status:
• Invalid status:

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