spring-projects/spring-ai · error · IllegalArgumentException

Unsupported image mime type: ${mimeType}

Error message

Unsupported image mime type: ${mimeType}

What it means

VertexAiMultimodalEmbeddingModel.doSingleDocumentPrediction routes each media item in a document by MIME type. When a media item's type is image-like handling fails — specifically, an image with a MIME type not accepted by the Vertex multimodal embedding API is both logged as a warning and thrown as IllegalArgumentException. Only supported image MIME types (e.g. image/png, image/jpeg) can be embedded.

Source

Thrown at models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/multimodal/VertexAiMultimodalEmbeddingModel.java:194

		Media media = document.getMedia();
		if (media != null) {
			if (media.getMimeType().isCompatibleWith(TEXT_MIME_TYPE)) {
				instanceBuilder.text(media.getData().toString());
				documentMetadata.put(ModalityType.TEXT,
						new DocumentMetadata(document.getId(), MimeTypeUtils.TEXT_PLAIN, media.getData()));
				if (logger.isWarnEnabled() && StringUtils.hasText(documentText)) {
					logger.warn("Media type String overrides the Document text content!");
				}
			}
			else if (media.getMimeType().isCompatibleWith(IMAGE_MIME_TYPE)) {
				if (SUPPORTED_IMAGE_MIME_SUB_TYPES.contains(media.getMimeType())) {
					instanceBuilder.image(ImageBuilder.of(media.getMimeType()).imageData(media.getData()).build());
					documentMetadata.put(ModalityType.IMAGE,
							new DocumentMetadata(document.getId(), media.getMimeType(), media.getData()));
				}
				else if (logger.isWarnEnabled()) {
					logger.warn("Unsupported image mime type: " + media.getMimeType());
					throw new IllegalArgumentException("Unsupported image mime type: " + media.getMimeType());
				}
			}
			else if (media.getMimeType().isCompatibleWith(VIDEO_MIME_TYPE)) {
				instanceBuilder.video(VideoBuilder.of(media.getMimeType())
					.videoData(media.getData())
					.startOffsetSec(mergedOptions.getVideoStartOffsetSec())
					.endOffsetSec(mergedOptions.getVideoEndOffsetSec())
					.intervalSec(mergedOptions.getVideoIntervalSec())
					.build());
				documentMetadata.put(ModalityType.VIDEO,
						new DocumentMetadata(document.getId(), media.getMimeType(), media.getData()));
			}
			else {
				if (logger.isWarnEnabled()) {
					logger.warn("Unsupported media type: " + media.getMimeType());
				}
				throw new IllegalArgumentException("Unsupported media type: " + media.getMimeType());
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

  1. Convert the image to a supported format (PNG or JPEG) before embedding
  2. Fix the MIME type on the Media/Document if the file is actually PNG/JPEG but typed incorrectly
  3. Pre-validate media MIME types in your pipeline and filter unsupported ones before calling the model

Example fix

// before
Media media = new Media(MimeTypeUtils.parseMimeType("image/webp"), data);
// after
Media media = new Media(new MimeType("image", "png"), pngBytes); // converted beforehand
Defensive patterns

Strategy: validation

Validate before calling

Set<MimeType> supported = Set.of(
    new MimeType("image","png"), new MimeType("image","jpeg"));
if (media.getMimeType() == null || !supported.contains(media.getMimeType())) {
    throw new IllegalArgumentException("Unsupported image type: " + media.getMimeType());
}

Try / catch

try {
    embeddingModel.embed(document);
} catch (IllegalArgumentException e) {
    // convert or drop the offending media item
}

Prevention

When it happens

Trigger: Embedding a Document whose media list contains an image Media whose getMimeType() is not compatible with the image builder's accepted types — e.g. image/webp, image/tiff, or a malformed/missing MIME type.

Common situations: Uploading screenshots in unsupported formats (webp, bmp); files stored without correct MIME metadata; passing generic application/octet-stream typed images.

Related errors

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