hibernate/hibernate-orm · error · UnsupportedOperationException

Wrap strategy not known for this Java type: " + getTypeName(

Error message

Wrap strategy not known for this Java type: " + getTypeName()

What it means

wrap() on a FormatMapperBasedJavaType accepts only null, instances of the mapped class, or a String that the format mapper deserializes. Any other input type — byte[], Map, driver JSONB objects — throws UnsupportedOperationException before any parsing happens.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/FormatMapperBasedJavaType.java:89

			return type.cast( getFormatMapper( typeConfiguration )
					.toString( value, this, options ) );
		}
		throw new UnsupportedOperationException(
				"Unwrap strategy not known for this Java type: " + getTypeName()
		);
	}

	@Override
	public <X> T wrap(X value, WrapperOptions options) {
		final var javaTypeClass = getJavaTypeClass();
		if ( javaTypeClass.isInstance( value ) ) {
			return javaTypeClass.cast( value );
		}
		else if ( value instanceof String string ) {
			return getFormatMapper( typeConfiguration )
					.fromString( string, this, options );
		}
		throw new UnsupportedOperationException(
				"Wrap strategy not known for this Java type: " + getTypeName()
		);
	}

	@Override
	public MutabilityPlan<T> getMutabilityPlan() {
		final var mutabilityPlan = super.getMutabilityPlan();
		return mutabilityPlan == null ? this : mutabilityPlan;
	}

	@Override
	public boolean isMutable() {
		return true;
	}

	@Override
	public T deepCopy(T value) {
		return value == null ? null : fromString( toString( value ) );

View on GitHub (pinned to fad1729dce)

Solutions

  1. Pass the JSON String and let fromString deserialize it
  2. Convert byte[] to String (UTF-8) before calling wrap
  3. Use the standard JSON JdbcType extractor so correctly typed values reach wrap()

Example fix

// before
Payload p = javaType.wrap(rs.getBytes(1), options); // byte[] -> throws

// after
Payload p = javaType.wrap(rs.getString(1), options); // String is deserialized by the mapper
Defensive patterns

Strategy: type-guard

Validate before calling

static boolean wrapInputOk(JavaType<?> jt, Object value) {
    return value == null || jt.getJavaTypeClass().isInstance(value) || value instanceof String;
}

Type guard

static boolean formatMapperWrapSupported(JavaType<?> jt, Object v) {
    return v == null || v instanceof String || jt.getJavaTypeClass().isInstance(v);
}

Try / catch

try {
    T v = javaType.wrap(raw, options);
} catch (UnsupportedOperationException e) {
    // convert raw to JSON text first, then let the format mapper deserialize
    T v = javaType.wrap(raw instanceof byte[] b ? new String(b, java.nio.charset.StandardCharsets.UTF_8) : (String) raw, options);
}

Prevention

When it happens

Trigger: Custom extractors passing raw driver values (PGobject, byte[]) into wrap(); deserializing from binary JSONB payloads; generic hydration code assuming wrap accepts anything serializable.

Common situations: Hand-written ResultSet readers for JSON columns; legacy type implementations migrated from Hibernate 5; binary JSON columns read with getBytes() instead of getString().

Related errors

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