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

UnknownBasicJavaType.wrap() throws UnsupportedOperationException('Wrap strategy not known for this Java type') when the incoming JDBC-side value is not an instance of the domain class - typically because the driver handed Hibernate a value in a different Java type (String, Number, driver class) and Hibernate cannot convert it without the loaded Class. It is the read-side mirror of the unwrap failure on the same unloadable-type descriptor.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/UnknownBasicJavaType.java:80

	}

	@Override
	public <X> X unwrap(T value, Class<X> type, WrapperOptions options) {
		if ( type.isAssignableFrom( getJavaTypeClass() ) ) {
			return type.cast( value );
		}
		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 );
		}
		throw new UnsupportedOperationException(
				"Wrap strategy not known for this Java type: " + getTypeName()
		);
	}

	@Override
	public String toString() {
		return "BasicJavaType(" + getTypeName() + ")";
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Fix class loading for the named type so a real JavaType with wrap strategies is used.
  2. Register an AttributeConverter or a concrete JavaType for the property so driver values are converted explicitly.
  3. Force a JdbcType whose extractor already returns the domain Java type (e.g. @JdbcTypeCode) to avoid the wrap step.

Example fix

// before: column read into a name-only registered type
@Entity public class Event {
    @Type("org.acme.Payload")  // class not loadable at runtime
    @Column(name = "payload") Payload payload;
}
// read -> wrap -> UnsupportedOperationException: Wrap strategy not known for this Java type

// after: register a converter so wrapping is explicit
@Entity public class Event {
    @Convert(converter = PayloadConverter.class)
    @Column(name = "payload") String payloadJson;
}
Defensive patterns

Strategy: validation

Validate before calling

// Verify no mapped property resolved to a placeholder descriptor before use
JavaType<?> jt = sessionFactory.getTypeConfiguration()
        .getJavaTypeRegistry()
        .findDescriptor(Payload.class);
if (jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType) {
    throw new IllegalStateException("Payload.class unresolved - reads will fail in wrap()");
}

Type guard

static boolean isResolvedJavaType(JavaType<?> jt) {
    return !(jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType);
}

Try / catch

try {
    E e = session.find(E.class, id);
} catch (UnsupportedOperationException ex) {
    if (ex.getMessage() != null && ex.getMessage().startsWith("Wrap strategy not known")) {
        // driver delivered the value in a different Java type: fix the descriptor/converter for that attribute
    } else {
        throw ex;
    }
}

Prevention

When it happens

Trigger: Extracting a column value into a domain type that resolved to UnknownBasicJavaType: the extractor produces e.g. a String or BigDecimal from the driver and calls wrap(value, options), which only succeeds on an exact instanceof match with the (unloadable) class.

Common situations: Runtime classloader differences so a type that 'worked' during bootstrap fails on read; hand-registered types by name; databases returning values in driver-specific Java types (Oracle TIMESTAMP, PGobject) that require conversion the placeholder descriptor cannot do.

Related errors

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