spring-projects/spring-ai · error · IllegalArgumentException

Unsupported media data type:

Error message

Unsupported media data type: 

What it means

OpenAiChatModel.fromMediaData accepts image/media content only as byte[] (encoded to a data URL) or as a String that is already a URL or user-supplied base64 payload. Any other type throws this IllegalArgumentException with the simple class name of the offending object.

Source

Thrown at models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatModel.java:996

	private String fromAudioData(Object audioData) {
		if (audioData instanceof byte[] bytes) {
			return Base64.getEncoder().encodeToString(bytes);
		}
		throw new IllegalArgumentException("Unsupported audio data type: " + audioData.getClass().getSimpleName());
	}

	private String fromMediaData(org.springframework.util.MimeType mimeType, Object mediaContentData) {
		if (mediaContentData instanceof byte[] bytes) {
			// Assume the bytes are an image. So, convert the bytes to a base64 encoded
			// following the prefix pattern.
			return String.format("data:%s;base64,%s", mimeType.toString(), Base64.getEncoder().encodeToString(bytes));
		}
		else if (mediaContentData instanceof String text) {
			// Assume the text is a URLs or a base64 encoded image prefixed by the user.
			return text;
		}
		else {
			throw new IllegalArgumentException(
					"Unsupported media data type: " + mediaContentData.getClass().getSimpleName());
		}
	}

	private List<ChatCompletionTool> getChatCompletionTools(List<ToolDefinition> toolDefinitions,
			@Nullable OpenAiChatOptions requestOptions) {
		return toolDefinitions.stream().map(toolDefinition -> {
			FunctionParameters.Builder parametersBuilder = FunctionParameters.builder();
			// Defaults to false: OpenAI's strict mode requires every schema property to
			// appear in "required" (optionality is expressed via nullable types, not
			// omission), which JsonSchemaGenerator does not produce by default. When a
			// caller opts in via OpenAiChatOptions#strict, applyStrictModeRequirements
			// below rewrites the schema to satisfy that contract.
			Boolean strictMode = false;
			if (requestOptions != null && requestOptions.getStrict() != null) {
				strictMode = requestOptions.getStrict();
			}
			else if (this.options != null && this.options.getStrict() != null) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Convert the object to byte[] (read the resource) or to its URL as a String (url.toString()) before constructing the Media.
2. If the data is a Path/File, use Files.readAllBytes(path) to pass bytes.
3. Check the actual runtime class named in the message and add an explicit conversion for it.

Example fix

// before
var media = new Media(MimeTypeUtils.IMAGE_PNG, new URI(urlString));
// after
var media = new Media(MimeTypeUtils.IMAGE_PNG, urlString);

if (!(mediaData instanceof byte[]) && !(mediaData instanceof String)) {
    throw new IllegalArgumentException("Media data must be byte[] or String (URL/base64), got: " + mediaData.getClass().getSimpleName());
}

static boolean isSupportedMediaData(Object data) {
    return data instanceof byte[] || data instanceof String;
}

try {
    response = chatModel.call(prompt);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported media data type")) {
        throw new InvalidMediaContentException("Use byte[] or a URL/base64 String for media content", e);
    }
    throw e;
}

When it happens

Trigger: Passing a Media content object whose data is neither byte[] nor String (e.g. URI, URL, Path, InputStream) into OpenAiChatModel.call, reaching OpenAiChatModel.java:996.

Common situations: Passing a java.net.URL or Path object because it 'looks like a URL', or an InputStream from a downloaded image, instead of bytes or a URL string.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unsupported media data type:
• Unsupported media data type: . Expected byte[] or String.
• Invalid Image content type:
• Unsupported media data type:
• Unsupported media data type:

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