spring-projects/spring-ai · error · IllegalStateException

Media data is not a byte[]

Error message

Media data is not a byte[]

What it means

getDataAsByteArray() returns the stored media payload as a byte array, but Media can hold other data types (e.g. Resource, URL-derived objects). If the internal data field is not a byte[], the method throws IllegalStateException instead of converting.

Solutions

1. Ensure the Media was built with byte[] data before calling getDataAsByteArray()
2. If data may be another type, obtain bytes via the builder/data(Resource) path or convert yourself
3. Catch IllegalStateException and fall back to a conversion path
4. For empty/null media, guard before calling (the method does not null-check semantics beyond instanceof)

Example fix

// before
byte[] bytes = media.getDataAsByteArray(); // IllegalStateException for non-byte[] data
// after
if (media.getData() instanceof byte[] bytes) {
    use(bytes);
} else {
    use(convertToBytes(media.getData()));
}

if (media.getData() instanceof byte[] b && b.length > 0) { /* safe */ }

static byte[] safeBytes(Media m) {
    return m.getData() instanceof byte[] b ? b : null;
}

try {
    byte[] b = media.getDataAsByteArray();
} catch (IllegalStateException e) {
    byte[] b = convert(media.getData());
}

When it happens

Trigger: Calling media.getDataAsByteArray() on a Media instance constructed via a constructor or builder path that stored a non-byte[] payload (URL, Resource-backed object) rather than raw bytes.

Common situations: Persisting/restoring chat memory with media created from URLs, then assuming the in-memory representation is raw bytes; calling the accessor defensively after deserialization.

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

• Invalid Image content type:
• Unsupported media data type:
• Unsupported media data 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/5f5d5d2e126ca1cc. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-commons/src/main/java/org/springframework/ai/content/Media.java:193

	/**
	 * Get the media data object.
	 * @return a {@link String} (URI/URL/base64), a {@code byte[]}, or a
	 * {@link java.net.URL}
	 */
	public Object getData() {
		return this.data;
	}

	/**
	 * Get the media data as a byte array
	 * @return the media data as a byte array
	 */
	public byte[] getDataAsByteArray() {
		if (this.data instanceof byte[]) {
			return (byte[]) this.data;
		}
		else {
			throw new IllegalStateException("Media data is not a byte[]");
		}
	}

	/**
	 * Get the media id
	 * @return the media id
	 */
	public @Nullable String getId() {
		return this.id;
	}

	/**
	 * Get the media name.
	 * @return the media name
	 */
	public String getName() {
		return this.name;
	}

View on GitHub (pinned to 98a7beda4f)