What causes "Cannot unwrap to requested type [" + unwrapType.getName() + "]" in hibernate/hibernate-orm?

Replace ignoreCase() with an explicit case-folding expression and select it: order by cb.lower(root.get("name")) with lower(name) in the select list.

hibernate/hibernate-orm · error · UnknownUnwrapTypeException

Cannot unwrap to requested type [" + unwrapType.getName() +

Error message

Cannot unwrap to requested type [" + unwrapType.getName() + "]

What it means

For a union-emulated full join, Hibernate can only order by positional references into the select list of the union branches. Ignore-case ordering would require a case-folded copy (lower/upper) of the sort column in that select list, which this emulation does not synthesize, so it rejects the query up front. This is a dialect limitation: on dialects with native FULL JOIN and native case-insensitive collation the same query works.

Source

Thrown at hibernate-agroal/src/main/java/org/hibernate/agroal/internal/AgroalConnectionProvider.java:224

	}

	@Override
	public boolean isUnwrappableAs(@Nonnull Class<?> unwrapType) {
		return unwrapType.isAssignableFrom( AgroalConnectionProvider.class )
			|| unwrapType.isAssignableFrom( AgroalDataSource.class );
	}

	@Override
	@SuppressWarnings( "unchecked" )
	public <T> T unwrap(@Nonnull Class<T> unwrapType) {
		if ( unwrapType.isAssignableFrom( AgroalConnectionProvider.class ) ) {
			return (T) this;
		}
		else if ( unwrapType.isAssignableFrom( AgroalDataSource.class ) ) {
			return (T) agroalDataSource;
		}
		else {
			throw new UnknownUnwrapTypeException( unwrapType );
		}
	}

	// --- Stoppable

	@Override
	public void stop() {
		if ( agroalDataSource != null ) {
			CONNECTION_INFO_LOGGER.cleaningUpConnectionPool(
					agroalDataSource.getConfiguration()
							.connectionPoolConfiguration()
							.connectionFactoryConfiguration()
							.jdbcUrl() );
			agroalDataSource.close();
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Replace ignoreCase() with an explicit case-folding expression and select it: order by cb.lower(root.get("name")) with lower(name) in the select list.
Do case-insensitive sorting in memory after fetching, or in a wrapping query outside the full join.
Define the column with a case-insensitive collation (e.g. utf8mb4_unicode_ci on MySQL) so a plain order by is already case-insensitive.
Avoid the full join for that query so no union emulation ordering is involved.

Example fix

// before: Criteria order with ignore-case + full join -> UnsupportedOperationException on MySQL
query.orderBy( cb.asc( root.get("name") ).ignoreCase() );

// after: explicit case-folding expression that is part of the select list
query.multiselect( root.get("id"), cb.lower( root.get("name") ) );
query.orderBy( cb.asc( cb.lower( root.get("name") ) ) );

Defensive patterns

Strategy: validation

Validate before calling

// Detect ignore-case ordering before executing on a full-join-emulating dialect
boolean hasIgnoreCaseOrder = criteriaQuery.getOrderList().stream()
    .anyMatch( o -> o instanceof JpaOrder j && j.isIgnoreCase() );
boolean emulatingDialect = dialect instanceof MySQLDialect || dialect instanceof MariaDBDialect
    || dialect instanceof SybaseDialect || dialect instanceof TiDBDialect;
if ( hasIgnoreCaseOrder && usesFullJoin && emulatingDialect ) {
    // convert to cb.lower(...) before running
}

Try / catch

try {
    return query.getResultList();
} catch ( UnsupportedOperationException e ) {
    if ( e.getMessage() != null && e.getMessage().contains("ignore case ordering") ) {
        return sortInMemoryIgnoreCase( queryWithoutFullJoin() );
    }
    throw e;
}

Prevention

Use explicit cb.lower()/lower() in HQL instead of Order.ignoreCase() when targeting MySQL/MariaDB/Sybase/TiDB.
Prefer case-insensitive column collations for natural case-insensitive sorting on those databases.
Smoke-test every dynamically generated sort combination against the production dialect.

When it happens

Trigger: An order-by created with ignore-case semantics - Criteria API Order.ignoreCase() (JPA 3.2) or SortSpecification with isIgnoreCase()==true - on a query containing a full join, translated by the MySQL/MariaDB/Sybase/SybaseASE/H2/TiDB translators. renderFullJoinEmulationSortExpression throws as soon as sortSpecification.isIgnoreCase() is true.

Common situations: Case-insensitive name sorting (users, cities, products) that used to run on PostgreSQL/SQL Server and is moved to MySQL/MariaDB; UI grid sorting with ignore-case flag enabled by default; JPA 3.2 migration where Order.ignoreCase() became available and developers adopted it widely.

Related errors

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