{"record":{"id":"8407aa0948d12db4","repo":"hibernate/hibernate-orm","slug":"configuration-property-hibernate-order-by-default","errorCode":null,"errorMessage":"Configuration property hibernate.order_by.default_null_ordering value '{}' is not recognized","messagePattern":"Configuration property hibernate\\.order_by\\.default_null_ordering value '(.+?)' is not recognized","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java","lineNumber":646,"sourceCode":"\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}\n\t\t\treturn parsed;\n\t\t}\n\t\telse if ( defaultNullPrecedence != null ) {\n\t\t\tthrow new IllegalArgumentException( \"Configuration property \" + DEFAULT_NULL_ORDERING\n\t\t\t\t\t\t\t\t\t\t\t\t+ \" value [\" + defaultNullPrecedence + \"] is not recognized\" );\n\t\t}\n\t\telse {\n\t\t\treturn Nulls.NONE;\n\t\t}\n\t}\n\n\t@Nullable\n\tprivate static Class<? extends SessionEventListener> getAutoSessionEventsListener(\n\t\t\tMap<String, Object> configurationSettings,\n\t\t\tStrategySelector strategySelector) {\n\t\t// todo : expose this from builder?","sourceCodeStart":628,"sourceCodeEnd":664,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java#L628-L664","documentation":"The hibernate.order_by.default_null_ordering setting is parsed with NullsHelper.parse, which matches the String (case-insensitively) against the jakarta.persistence.criteria.Nulls enum values: none, first, last. An unrecognized String yields null from the parser and SessionFactoryOptionsBuilder throws IllegalArgumentException, aborting SessionFactory bootstrap.","triggerScenarios":"Setting hibernate.order_by.default_null_ordering to any string other than none/first/last (case-insensitive), e.g. 'nulls_first', 'high', 'smallest', 'asc_nulls_first', or a value with surrounding whitespace.","commonSituations":"Porting PostgreSQL/Oracle hint vocabulary ('NULLS FIRST') into the property; using values from SQL ORDER BY clauses or other ORMs; whitespace from a YAML/ENV-injected value; downgrading knowledge from docs listing different keywords.","solutions":["Use exactly one of: none, first, last (case-insensitive)","Or pass the typed value directly: props.put(\"hibernate.order_by.default_null_ordering\", Nulls.FIRST) with jakarta.persistence.criteria.Nulls","Trim values sourced from environment variables or YAML before setting them","Remove the property entirely — the default is Nulls.NONE"],"exampleFix":"# before:\nhibernate.order_by.default_null_ordering = nulls_first\n\n# after:\nhibernate.order_by.default_null_ordering = first","handlingStrategy":"validation","validationCode":"// validate before boot\nstatic boolean isValidNullOrdering(String s) {\n    if (s == null) return true;\n    return Arrays.stream(Nulls.values()).anyMatch(n -> n.name().equalsIgnoreCase(s.trim()));\n}\n\nif (!isValidNullOrdering(props.getProperty(\"hibernate.order_by.default_null_ordering\")))\n    throw new IllegalArgumentException(\"Use none, first, or last\");","typeGuard":"static String sanitizeNullOrdering(String raw) {\n    if (raw == null) return null;\n    String v = raw.trim().toLowerCase(Locale.ROOT);\n    return switch (v) { case \"none\", \"first\", \"last\" -> v; default -> null; };\n}","tryCatchPattern":"try {\n    sessionFactory = configuration.buildSessionFactory();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"hibernate.order_by.default_null_ordering\")) {\n        props.put(\"hibernate.order_by.default_null_ordering\", Nulls.NONE.toString()); // known-good default\n    } else throw e;\n}","preventionTips":["Use the typed enum (jakarta.persistence.criteria.Nulls) in code instead of strings","Trim and lowercase values injected from ENV/YAML before use","Document the three legal values (none/first/last) next to every place the property is set"],"tags":["hibernate","configuration","ordering","null-precedence"],"backgroundTag":"invalid-configuration-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}