hibernate/hibernate-orm · error · UnsupportedOperationException

Unwrap strategy not known for this Java type: " + getTypeNam

Error message

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

What it means

UnknownBasicJavaType.unwrap() only supports a plain cast when the requested target type is assignable from the (never loaded) domain class; any other target throws UnsupportedOperationException('Unwrap strategy not known for this Java type'). Without the real Class, Hibernate cannot build an actual conversion. It fires at bind time when the chosen JdbcType needs the value in a different Java type.

Source

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

		}
		else {
			return type;
		}
	}

	@Override
	public JdbcType getRecommendedJdbcType(JdbcTypeIndicators context) {
		throw new JdbcTypeRecommendationException(
				"Could not determine recommended JdbcType for Java type '" + getTypeName() + "'"
		);
	}

	@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. Resolve the classpath/classloader problem so the real JavaType is registered and real unwrap strategies exist.
2. Register an explicit JavaType or AttributeConverter for the type so conversions are concrete.
3. Annotate the attribute with an explicit @JdbcType whose binder accepts a pass-through of the domain Java type.

Example fix

// before: type only known by name; driver path needs String unwrap
session.createQuery("from E e where e.payload = :p", E.class).setParameter("p", payload);
// unwrap -> UnsupportedOperationException: Unwrap strategy not known for this Java type

// after: make the class loadable (fix classpath) and/or register the descriptor explicitly
public class MyPayloadJavaType extends AbstractJavaType<MyPayload> {
    @Override
    public <X> X unwrap(MyPayload value, Class<X> type, WrapperOptions options) {
        if (String.class.isAssignableFrom(type)) return type.cast(value.toString());
        throw unknownUnwrap(type);
    }
}

// After bootstrap, verify the descriptor for your domain type is real
JavaType<?> jt = sessionFactory.getTypeConfiguration()
        .getJavaTypeRegistry()
        .findDescriptor(MyType.class);
if (jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType) {
    throw new IllegalStateException("MyType did not load - fix the classpath before querying");
}

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

try {
    session.createQuery("from E e where e.payload = :p", E.class)
           .setParameter("p", value).getResultList();
} catch (UnsupportedOperationException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unwrap strategy not known")) {
        // domain type was registered as UnknownBasicJavaType: fix classpath or register a JavaType/converter
    } else {
        throw e;
    }
}

When it happens

Trigger: Reading or writing a column whose domain Java type resolved to UnknownBasicJavaType, while the selected JdbcType's binder/extractor requests a different Java type through WrapperOptions - e.g. a dialect whose getPreferredJavaTypeClass() differs from the domain class, or binding through java.sql.Array/String paths.

Common situations: Classpath/classloader mismatches at runtime (containers, hot reload, native image) where the type loads at bootstrap tooling time but not at runtime; custom mappings that depend on name-only type registration and then hit driver-specific conversions.

Related errors

• Wrap strategy not known for this Java type: " + getTypeName(
• Unknown unwrap conversion requested: " + type.getTypeName()
• Illegal attempt to treat 'java.sql.Date' as 'java.sql.Time'
• Illegal attempt to treat `java.sql.Time` as `java.sql.Date`
• Cannot convert changeset timestamp to Instant: <value>

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