{"record":{"id":"3eb1cc5b793037a4","repo":"hibernate/hibernate-orm","slug":"could-not-transform-the-raw-jdbc-value-3eb1cc","errorCode":null,"errorMessage":"Could not transform the raw jdbc value","messagePattern":"Could not transform the raw jdbc value","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/type/OracleStructJdbcType.java","lineNumber":55,"sourceCode":"\t\t\t\tsqlType,\n\t\t\t\tcreationContext.getBootModel()\n\t\t\t\t\t\t.getDatabase()\n\t\t\t\t\t\t.getDefaultNamespace()\n\t\t\t\t\t\t.locateUserDefinedType( Identifier.toIdentifier( sqlType ) )\n\t\t\t\t\t\t.getOrderMapping()\n\t\t);\n\t}\n\n\t@Override\n\tprotected Object transformRawJdbcValue(Object rawJdbcValue, WrapperOptions options) {\n\t\tif ( rawJdbcValue.getClass() == TIMESTAMPTZ.class ) {\n\t\t\ttry {\n\t\t\t\treturn ( (TIMESTAMPTZ) rawJdbcValue ).offsetDateTimeValue(\n\t\t\t\t\t\toptions.getSession().getJdbcCoordinator().getLogicalConnection().getPhysicalConnection()\n\t\t\t\t);\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException( \"Could not transform the raw jdbc value\", e );\n\t\t\t}\n\t\t}\n\t\treturn rawJdbcValue;\n\t}\n\n}\n","sourceCodeStart":37,"sourceCodeEnd":62,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/type/OracleStructJdbcType.java#L37-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n@Embeddable\n@Struct(name = \"event_t\")\npublic class Event {\n    private OffsetDateTime at;  // oracle.sql.TIMESTAMPTZ conversion needs live connection\n}\n// after (workaround when conversion keeps failing)\n@Embeddable\n@Struct(name = \"event_t\")\npublic class Event {\n    private String at;          // read raw, convert in Java\n    public OffsetDateTime at() { return OffsetDateTime.parse(at); }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (HibernateException e) {\n    if (\"Could not transform the raw jdbc value\".equals(e.getMessage())\n            && e.getCause() != null) {\n        // cause comes from oracle.sql.TIMESTAMPTZ.offsetDateTimeValue(connection)\n        log.error(\"TIMESTAMPTZ conversion failed (connection state/timezone): {}\", e.getCause(), e);\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["oracle","struct","timestamptz","timezone","jdbc-driver"],"backgroundTag":"oracle-struct-value-conversion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}