spring-projects/spring-ai · error · IllegalArgumentException

Unable to detect the MIME type of '%s'. Please provide it ex

Error message

Unable to detect the MIME type of '%s'. Please provide it explicitly.

What it means

MimeTypeDetector.getMimeType(Resource) resolves the resource URI then looks up its MIME type; if resolving the URI throws IOException, it throws IllegalArgumentException saying the MIME type could not be detected and must be provided explicitly. The detector cannot even read the resource location to guess a type.

Source

Thrown at models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/MimeTypeDetector.java:83

	public static MimeType getMimeType(URI uri) {
		return getMimeType(uri.toString());
	}

	public static MimeType getMimeType(File file) {
		return getMimeType(file.getAbsolutePath());
	}

	public static MimeType getMimeType(Path path) {
		return getMimeType(path.toUri());
	}

	public static MimeType getMimeType(Resource resource) {
		try {
			return getMimeType(resource.getURI());
		}
		catch (IOException e) {
			throw new IllegalArgumentException(
					String.format("Unable to detect the MIME type of '%s'. Please provide it explicitly.",
							resource.getFilename()),
					e);
		}
	}

	public static MimeType getMimeType(String path) {

		int dotIndex = path.lastIndexOf('.');

		if (dotIndex != -1 && dotIndex < path.length() - 1) {
			String extension = path.substring(dotIndex + 1);
			MimeType customMimeType = GEMINI_MIME_TYPES.get(extension);
			if (customMimeType != null) {
				return customMimeType;
			}
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Explicitly set the MimeType on the Media/MediaPart instead of relying on detection.
2. Verify the resource exists (resource.exists()) and its path/URL is correct before passing it.
3. Check that files referenced on the classpath are actually packaged in the jar.
4. Inspect the cause IOException for the underlying resolution failure.

Example fix

// before
new Media(null, resource); // detection fails for unresolvable resource
// after
new Media(MimeTypeUtils.IMAGE_PNG, resource);

if (!resource.exists()) throw new IllegalStateException("resource missing: " + resource);
URI uri = resource.getURI(); // fail fast if unresolvable

try { MimeType mt = MimeTypeDetector.getMimeType(resource); } catch (IllegalArgumentException e) { useExplicitMimeType(); }

When it happens

Trigger: Passing a Resource whose getURI() fails — e.g. a ClassPathResource that doesn't exist, an unreadable file, a broken URL resource — to Gemini media parts via Media or media APIs.

Common situations: Typos in classpath paths (missing leading slash conventions); files deleted or not on the classpath at runtime; resources inside nested jars; remote URLs with connection problems.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Unsupported image mime type: ${mimeType}
• Unsupported media type: ${mimeType}
• Unsupported media format:
• Unsupported media format:
• Unsupported document format:

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