hibernate/hibernate-orm · error · HibernateException

Expecting raw JDBC value of type `%s`, but found `%s` : [%s]

Error message

Expecting raw JDBC value of type `%s`, but found `%s` : [%s]

What it means

BasicResultAssembler applies a valueConverter (AttributeConverter-backed or otherwise) to the raw JDBC value after checking that the raw value is an instance of the converter's relational Java type. If the JDBC driver returns a different runtime type than the converter's relational type declares - String vs UUID, or a driver-specific class - Hibernate throws HibernateException 'Expecting raw JDBC value of type `X`, but found `Y`'.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/results/graph/basic/BasicResultAssembler.java:63

	/**
	 * Access to the raw value (unconverted, if a converter applied)
	 */
	public Object extractRawValue(RowProcessingState rowProcessingState) {
		if ( unwrapRowProcessingState ) {
			rowProcessingState = rowProcessingState.unwrap();
		}
		return rowProcessingState.getJdbcValue( valuesArrayPosition );
	}

	@Override
	public J assemble(RowProcessingState rowProcessingState) {
		final Object jdbcValue = extractRawValue( rowProcessingState );

		if ( valueConverter != null ) {
			if ( jdbcValue != null
					// the raw value type should be the converter's relational-JTD
					&& !valueConverter.getRelationalJavaType().isInstance( jdbcValue ) ) {
				throw new HibernateException(
						String.format(
								Locale.ROOT,
								"Expecting raw JDBC value of type `%s`, but found `%s` : [%s]",
								valueConverter.getRelationalJavaType().getTypeName(),
								jdbcValue.getClass().getName(),
								jdbcValue
						)
				);
			}
			// Safe unchecked cast due to check above
			@SuppressWarnings({"unchecked", "rawtypes"})
			final Object domainValue =
					( (BasicValueConverter) valueConverter )
							.toDomainValue( jdbcValue );
			return (J) domainValue;
		}
		else {
			return (J) jdbcValue;

View on GitHub (pinned to fad1729dce)

Solutions

1. Align the converter's relational type with what the driver returns - for a native UUID column use AttributeConverter<UUID,UUID> or map the attribute as UUID without a converter
2. Force extraction to the expected type: annotate with @JdbcTypeCode(SqlTypes.VARCHAR) (or the fitting JdbcType) so raw values arrive as the converter's relational type
3. Upgrade Hibernate/the dialect - improved JavaType/JdbcType resolution fixed several driver-type mismatches
4. Verify with a smoke test that reads one row of each converted column right after startup, so mismatches surface at deploy time, not mid-request

Example fix

// before
@Converter
public class UuidConverter implements AttributeConverter<UUID, String> { ... } // column is native uuid

// after
// map native uuid columns as UUID directly, no converter
@JdbcTypeCode( SqlTypes.UUID )
private UUID documentId;

// smoke test at startup: read one row of every converter-mapped column
converterMappedAttributes.forEach( attr ->
    session.createQuery( "select e." + attr + " from Entity e", Object.class )
           .setMaxResults( 1 ).getResultList() );

try {
    return query.list();
} catch ( HibernateException e ) {
    if ( e.getMessage() != null && e.getMessage().startsWith( "Expecting raw JDBC value of type" ) ) {
        // converter relational type mismatched the driver type: fix @JdbcTypeCode / converter
        throw new IllegalStateException( "Mapping/driver mismatch on a converted column: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: A converter whose relational type mismatches what the driver returns for the column: AttributeConverter<UUID,String> against a native UUID column (PostgreSQL returns java.util.UUID), converters on TIMESTAMP columns where the driver returns its own timestamp class, custom JdbcType pairings with the wrong relational Java type.

Common situations: PostgreSQL/Oracle native column types with converters written for String; switching or upgrading JDBC drivers (ojdbc, mssql-jdbc) changing extracted runtime types; @JdbcTypeCode mismatches after Hibernate upgrades.

Related errors

• Unable to determine SQL type name for column '%s' of table '
• Could not determine recommended JdbcType for `" + getTypeNam
• unknown type: {sqlTypeCode}
• Unable to determine SQL type name for column '%s' of table '
• Could not format discriminator value to SQL string

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