What causes "The byte[] must not be null" in hibernate/hibernate-orm?

Null-check (and ideally emptiness-check) the byte array before calling deserialize and fail with a contextual message naming the source.

hibernate/hibernate-orm · error · IllegalArgumentException

The byte[] must not be null

Error message

The byte[] must not be null

What it means

deserialize(byte[]) funnels through a private wrap(byte[]) helper that must turn the array into a ByteArrayInputStream; a null array fails fast there with IllegalArgumentException before any stream construction or classloading happens. This is a plain null-hostile argument contract on the byte-array convenience overload.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/SerializationHelper.java:229

	 * Thread Context ClassLoader (TCCL). If there is no TCCL set,
	 * the classloader of the calling class is used.
	 * <p>
	 * Delegates to {@link #deserialize(byte[], ClassLoader)}
	 *
	 * @param objectData the serialized object, must not be null
	 *
	 * @return the deserialized object
	 *
	 * @throws IllegalArgumentException if <code>objectData</code> is <code>null</code>
	 * @throws SerializationException (runtime) if the serialization fails
	 */
	public static Object deserialize(byte[] objectData) throws SerializationException {
		return doDeserialize( wrap( objectData ), defaultClassLoader(), hibernateClassLoader(), null );
	}

	private static InputStream wrap(byte[] objectData) {
		if ( objectData == null ) {
			throw new IllegalArgumentException( "The byte[] must not be null" );
		}
		return new ByteArrayInputStream( objectData );
	}

	/**
	 * Deserializes an object from an array of bytes.
	 * <p>
	 * Delegates to {@link #deserialize(InputStream, ClassLoader)} using a
	 * {@link ByteArrayInputStream} to wrap the array.
	 *
	 * @param objectData the serialized object, must not be null
	 * @param loader The classloader to use
	 *
	 * @return the deserialized object
	 *
	 * @throws IllegalArgumentException if <code>objectData</code> is <code>null</code>
	 * @throws SerializationException (runtime) if the serialization fails
	 */

View on GitHub (pinned to fad1729dce)

Solutions

Null-check (and ideally emptiness-check) the byte array before calling deserialize and fail with a contextual message naming the source.
Model 'no data' explicitly (Optional.empty / null return) instead of routing null into deserialization.

Example fix

// before
byte[] blob = rs.getBytes("payload"); // null when column is NULL
Object o = SerializationHelper.deserialize(blob); // IllegalArgumentException

// after
byte[] blob = rs.getBytes("payload");
if (blob == null) return null; // column NULL -> no payload
Object o = SerializationHelper.deserialize(blob);

Defensive patterns

Strategy: validation

Validate before calling

if (objectData == null || objectData.length == 0) {
    return null; // no payload stored
}
Object o = SerializationHelper.deserialize(objectData);

Prevention

Null-check byte arrays from database reads (NULL columns come back as null).
Use Optional or explicit null returns to model missing payloads instead of passing null on.

When it happens

Trigger: Calling SerializationHelper.deserialize((byte[]) null) or deserialize(null, loader), typically because the blob fetch returned null (row absent, cache miss modeled as null) and the caller passed it through.

Common situations: Cache or repository methods that return null on miss, piped directly into deserialize; optional columns read as null from the database; tests using null placeholders.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/7f2e05ab61678bb2. Report an issue: GitHub.