spring-projects/spring-ai · error · IllegalArgumentException

Unknown ResponseFormat type:

Error message

Unknown ResponseFormat type:

What it means

MistralAiApi.ResponseFormat.Type.fromValue() deserializes the 'response_format' type string returned by (or supplied to) the Mistral API. It throws IllegalArgumentException when the string does not match one of the known enum values (e.g. "text", "json_object"). This protects callers from silently working with an unrecognized response format.

Source

Thrown at models/spring-ai-mistral-ai/src/main/java/org/springframework/ai/mistralai/api/MistralAiApi.java:1041

				JSON_SCHEMA("json_schema");

				private final String value;

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

				public String getValue() {
					return this.value;
				}

				public static Type fromValue(String value) {
					for (Type type : Type.values()) {
						if (type.value.equals(value)) {
							return type;
						}
					}
					throw new IllegalArgumentException("Unknown ResponseFormat type: " + value);
				}

			}

			/**
			 * JSON schema object that describes the format of the JSON object. Applicable
			 * for the 'json_schema' type only.
			 */
			@JsonInclude(Include.NON_NULL)
			public static class JsonSchema {

				@JsonProperty("name")
				private String name;

				@JsonProperty("schema")
				private Map<String, Object> schema;

				@JsonProperty("strict")

View on GitHub (pinned to 98a7beda4f)

Solutions

  1. Upgrade spring-ai-mistral-ai to the latest version so the enum includes newly added Mistral response format types.
  2. Check the exact value string in the payload/response and correct typos (must match a known enum value such as "text" or "json_object").
  3. If a new Mistral type is genuinely unsupported, construct the request without response_format or use a supported type instead.

Example fix

// before
ResponseFormat.Type.fromValue("json"); // throws
// after
ResponseFormat.Type.fromValue("json_object"); // valid enum value
Defensive patterns

Strategy: try-catch

Validate before calling

String type = responseFormat != null ? responseFormat.getType() : null;
if (type == null || !(type.equals("text") || type.equals("json_object"))) {
    throw new IllegalArgumentException("Unsupported response_format type: " + type);
}

Type guard

boolean isKnownResponseType(String v) { return v != null && (v.equals("text") || v.equals("json_object")); }

Try / catch

try {
    var t = MistralAiApi.ResponseFormat.Type.fromValue(value);
} catch (IllegalArgumentException e) {
    // fall back to ResponseFormat for a known-safe value or skip response_format
}

Prevention

When it happens

Trigger: Deserializing a Mistral chat completion response whose response_format.type string is not one of the enum values, or programmatically calling Type.fromValue() with a typo'd/unsupported value like "json" or an empty string.

Common situations: Mistral adds a new response_format type in their API while the Spring AI version in use predates it; hand-written JSON fixtures or mocks with misspelled type values; users constructing a ResponseFormat manually with a wrong type string.

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

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/4143e400d6d3be61. Report an issue: GitHub.