What causes "Could not transform the raw jdbc value" in hibernate/hibernate-orm?

Access struct attributes while the session and its connection are still open - materialize values eagerly inside the transaction.

hibernate/hibernate-orm · error · HibernateException

Could not transform the raw jdbc value

Error message

Could not transform the raw jdbc value

What it means

OracleStructJdbcType.transformRawJdbcValue converts raw oracle.sql.TIMESTAMPTZ attribute values read from Oracle STRUCT columns by calling offsetDateTimeValue(physicalConnection). If that driver call throws, Hibernate wraps it in HibernateException with this message. The failure is inside the Oracle driver's conversion and is almost always tied to the connection state passed in (closed/stale) or to timezone data the driver cannot resolve.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/dialect/type/OracleStructJdbcType.java:55

				sqlType,
				creationContext.getBootModel()
						.getDatabase()
						.getDefaultNamespace()
						.locateUserDefinedType( Identifier.toIdentifier( sqlType ) )
						.getOrderMapping()
		);
	}

	@Override
	protected Object transformRawJdbcValue(Object rawJdbcValue, WrapperOptions options) {
		if ( rawJdbcValue.getClass() == TIMESTAMPTZ.class ) {
			try {
				return ( (TIMESTAMPTZ) rawJdbcValue ).offsetDateTimeValue(
						options.getSession().getJdbcCoordinator().getLogicalConnection().getPhysicalConnection()
				);
			}
			catch (Exception e) {
				throw new HibernateException( "Could not transform the raw jdbc value", e );
			}
		}
		return rawJdbcValue;
	}

}

View on GitHub (pinned to fad1729dce)

Solutions

Access struct attributes while the session and its connection are still open - materialize values eagerly inside the transaction.
Align timezone data: set -Duser.timezone to a valid zone, try -Doracle.jdbc.timezoneAsRegion=false, and update the DB timezone file.
Upgrade ojdbc to the version matching the Oracle database release.
Map the attribute as String within the struct embeddable and parse it yourself to avoid the driver conversion.

Example fix

// before
@Embeddable
@Struct(name = "event_t")
public class Event {
    private OffsetDateTime at;  // oracle.sql.TIMESTAMPTZ conversion needs live connection
}
// after (workaround when conversion keeps failing)
@Embeddable
@Struct(name = "event_t")
public class Event {
    private String at;          // read raw, convert in Java
    public OffsetDateTime at() { return OffsetDateTime.parse(at); }
}

Defensive patterns

Strategy: try-catch

Try / catch

catch (HibernateException e) {
    if ("Could not transform the raw jdbc value".equals(e.getMessage())
            && e.getCause() != null) {
        // cause comes from oracle.sql.TIMESTAMPTZ.offsetDateTimeValue(connection)
        log.error("TIMESTAMPTZ conversion failed (connection state/timezone): {}", e.getCause(), e);
    }
    throw e;
}

Prevention

Keep the session open until all Oracle object-type attributes have been read.
Fix the JVM/DB timezone configuration instead of relying on driver defaults.
Prefer timestamp columns over object types containing TIMESTAMPTZ where you control the schema.

When it happens

Trigger: Reading an @Struct-mapped Oracle object whose attribute is TIMESTAMP WITH TIME ZONE, where oracle.sql.TIMESTAMPTZ.offsetDateTimeValue(connection) fails: physical connection already closed when the struct attribute is materialized (detached entity, lazy access), session timezone region unavailable, or an ojdbc/DB timezone data mismatch.

Common situations: Entities with Oracle object-type columns containing TIMESTAMPTZ accessed after the owning session closed; databases upgraded to newer timezone files than the driver knows; JVM default timezone set to a region the driver maps badly.

Related errors

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