{"record":{"id":"d339e2b1544f9e9e","repo":"hibernate/hibernate-orm","slug":"configuration-property-hibernate-jdbc-time-zone-va","errorCode":null,"errorMessage":"Configuration property hibernate.jdbc.time_zone value [{}] is not supported","messagePattern":"Configuration property hibernate\\.jdbc\\.time_zone value \\[(.+?)\\] is not supported","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java","lineNumber":630,"sourceCode":"\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new RuntimeException( \"Unable to instantiate StatementObserver - \" + setting, e );\n\t\t}\n\t}\n\n\t@Nullable\n\tprivate TimeZone getJdbcTimeZone(Object jdbcTimeZoneValue) {\n\t\tif ( jdbcTimeZoneValue instanceof TimeZone timeZone ) {\n\t\t\treturn timeZone;\n\t\t}\n\t\telse if ( jdbcTimeZoneValue instanceof ZoneId zoneId ) {\n\t\t\treturn TimeZone.getTimeZone( zoneId );\n\t\t}\n\t\telse if ( jdbcTimeZoneValue instanceof String string ) {\n\t\t\treturn TimeZone.getTimeZone( ZoneId.of( string ) );\n\t\t}\n\t\telse if ( jdbcTimeZoneValue != null ) {\n\t\t\tthrow new IllegalArgumentException( \"Configuration property \" + JDBC_TIME_ZONE\n\t\t\t\t\t\t\t\t\t\t\t\t+ \" value [\" + jdbcTimeZoneValue + \"] is not supported\" );\n\t\t}\n\t\telse {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Nonnull\n\tprivate Nulls getDefaultNullPrecedence(Object defaultNullPrecedence) {\n\t\tif ( defaultNullPrecedence instanceof Nulls jpaValue ) {\n\t\t\treturn jpaValue;\n\t\t}\n\t\telse if ( defaultNullPrecedence instanceof String string ) {\n\t\t\tfinal var parsed = NullsHelper.parse( string );\n\t\t\tif ( parsed == null ) {\n\t\t\t\tthrow new IllegalArgumentException( \"Configuration property \" + DEFAULT_NULL_ORDERING\n\t\t\t\t\t\t\t\t\t\t\t\t\t+ \" value '\" + defaultNullPrecedence + \"' is not recognized\" );\n\t\t\t}","sourceCodeStart":612,"sourceCodeEnd":648,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java#L612-L648","documentation":"The hibernate.jdbc.time_zone setting accepts only a java.util.TimeZone, a java.time.ZoneId, a String parseable by ZoneId.of (e.g. 'UTC', 'Europe/Berlin', 'GMT+2'), or nothing at all. SessionFactoryOptionsBuilder.getJdbcTimeZone throws IllegalArgumentException for any other non-null value type, failing SessionFactory bootstrap. Note: a String that is not a valid zone id throws ZoneRulesException instead — this error is specifically about the value's type.","triggerScenarios":"Passing hibernate.jdbc.time_zone as an Integer/Long offset (e.g. 2), a boolean, an org.joda.time.DateTimeZone, or any custom object — anything that is not TimeZone, ZoneId, or String.","commonSituations":"Reading the offset from an environment variable into a numeric type and putting it into properties directly; migrating code that used a Joda-Time zone; Spring's environment binding coercing the value to a non-string type; passing a Calendar.","solutions":["Use a java.time.ZoneId or java.util.TimeZone instance: props.put(JdbcSettings.JDBC_TIME_ZONE, ZoneId.of(\"UTC\"))","Or use a valid ZoneId string: 'UTC', 'Europe/Berlin', or offset form 'GMT+02:00'","Convert numeric offsets to a zone string before setting (e.g. String.format(\"GMT%+02d:00\", offset))","Leave the property unset to use the JVM default"],"exampleFix":"// before:\nprops.put(\"hibernate.jdbc.time_zone\", 2); // Integer -> IllegalArgumentException\n\n// after:\nprops.put(\"hibernate.jdbc.time_zone\", ZoneId.of(\"GMT+02:00\")); // or the String \"GMT+02:00\"","handlingStrategy":"validation","validationCode":"// normalize the value to a supported type before passing it to Hibernate\nstatic Object normalizeJdbcTimeZone(Object raw) {\n    if (raw == null || raw instanceof TimeZone || raw instanceof ZoneId) return raw;\n    if (raw instanceof String s) return ZoneId.of(s.trim()); // throws early with a clear ZoneId error\n    if (raw instanceof Integer offset) return ZoneId.of(String.format(\"GMT%+03d:00\", offset));\n    throw new IllegalArgumentException(\"Unsupported jdbc time zone value type: \" + raw.getClass());\n}\n\nprops.put(JdbcSettings.JDBC_TIME_ZONE, normalizeJdbcTimeZone(rawValue));","typeGuard":"static boolean isSupportedTimeZoneValue(Object v) {\n    return v == null || v instanceof java.util.TimeZone\n        || v instanceof java.time.ZoneId || v instanceof String;\n}","tryCatchPattern":"try {\n    sessionFactory = configuration.buildSessionFactory();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"hibernate.jdbc.time_zone\")) {\n        props.put(\"hibernate.jdbc.time_zone\", ZoneId.systemDefault().getId()); // safe value, rebuild\n    } else throw e;\n}","preventionTips":["Always set hibernate.jdbc.time_zone from a java.time.ZoneId or a verified zone-id string","Never feed environment-parsed ints or third-party zone types directly into Hibernate properties","Fail fast at config-load time by validating property value types in one place"],"tags":["hibernate","configuration","jdbc","timezone","type-mismatch"],"backgroundTag":"invalid-configuration-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}