{"record":{"id":"87d6d02af4d4a092","repo":"hibernate/hibernate-orm","slug":"configuration-property-hibernate-order-by-default-87d6d0","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":652,"sourceCode":"\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?\n\t\tfinal String name = (String) configurationSettings.get( AUTO_SESSION_EVENTS_LISTENER );\n\t\treturn name == null ? null : strategySelector.selectStrategyImplementor( SessionEventListener.class, name );\n\t}\n\n\tprivate static boolean disallowBatchUpdates(Dialect dialect, ExtractedDatabaseMetaData meta) {\n\t\tfinal Boolean dialectAnswer = dialect.supportsBatchUpdates();","sourceCodeStart":634,"sourceCodeEnd":670,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java#L634-L670","documentation":"When hibernate.order_by.default_null_ordering holds a non-null value that is neither a jakarta.persistence.criteria.Nulls enum nor a String, SessionFactoryOptionsBuilder throws IllegalArgumentException at bootstrap. The message uses square brackets to signal the failure is about the value's type, not its textual content.","triggerScenarios":"Putting an Integer (e.g. 1), Boolean, or an enum of a different type (such as the pre-Hibernate-7 org.hibernate.NullPrecedence or a custom enum) into hibernate.order_by.default_null_ordering.","commonSituations":"Upgrading Hibernate where code passed the old NullPrecedence enum that was replaced by Nulls; Spring/type-safe configuration binding an int constant; copy-pasting values between settings blocks of different types.","solutions":["Pass a jakarta.persistence.criteria.Nulls enum value (Nulls.NONE, Nulls.FIRST, Nulls.LAST)","Or pass the equivalent String 'none'/'first'/'last'","After a Hibernate upgrade, replace removed enum types like org.hibernate.NullPrecedence with Nulls","Set the value through typed APIs (e.g. SessionFactoryBuilder) rather than raw maps when possible"],"exampleFix":"// before (old Hibernate 6 enum, removed later):\nprops.put(\"hibernate.order_by.default_null_ordering\", org.hibernate.NullPrecedence.FIRST);\n\n// after:\nprops.put(\"hibernate.order_by.default_null_ordering\", jakarta.persistence.criteria.Nulls.FIRST);","handlingStrategy":"validation","validationCode":"// ensure the property value is Nulls or String before boot\nObject v = props.get(\"hibernate.order_by.default_null_ordering\");\nif (v != null && !(v instanceof Nulls) && !(v instanceof String))\n    throw new IllegalArgumentException(\n        \"hibernate.order_by.default_null_ordering must be Nulls or String, got \" + v.getClass());","typeGuard":"static boolean isSupportedNullOrderingValue(Object v) {\n    return v == null || v instanceof jakarta.persistence.criteria.Nulls || v instanceof String;\n}","tryCatchPattern":"try {\n    sessionFactory = configuration.buildSessionFactory();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"default_null_ordering\")) {\n        props.put(\"hibernate.order_by.default_null_ordering\", Nulls.NONE); // typed known-good value\n    } else throw e;\n}","preventionTips":["After a Hibernate upgrade, grep for org.hibernate.NullPrecedence and migrate to Nulls","Set the property from typed code, not untyped maps sourced from config files","Add a config-loader unit test asserting value types for known settings"],"tags":["hibernate","configuration","ordering","null-precedence","type-mismatch"],"backgroundTag":"invalid-configuration-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}