{"record":{"id":"c7bb8900604a1538","repo":"hibernate/hibernate-orm","slug":"literal-value-cannot-be-null","errorCode":null,"errorMessage":"literal value cannot be null","messagePattern":"literal value cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmCriteriaNodeBuilder.java","lineNumber":1963,"sourceCode":"\t\t\t\t\tresolveEnumType( typeConfiguration, enumValue );\n\t\t}\n\t\telse {\n\t\t\treturn result;\n\t\t}\n\t}\n\n\tprivate static <E extends Enum<E>> BasicType<E> resolveEnumType(TypeConfiguration configuration, Enum<E> enumValue) {\n\t\tfinal var enumJavaType = new EnumJavaType<>( ReflectHelper.getClass( enumValue ) );\n\t\tfinal var jdbcType = enumJavaType.getRecommendedJdbcType( configuration.getCurrentBaseSqlTypeIndicators() );\n\t\treturn configuration.getBasicTypeRegistry().resolve( enumJavaType, jdbcType );\n\t}\n\n\t@Nonnull\n\t@Override\n\tpublic <T> SqmLiteral<T> literal(@Nonnull T value) {\n\t\tif ( value == null ) {\n\t\t\tif ( jpaCompliance.isJpaQueryComplianceEnabled() ) {\n\t\t\t\tthrow new IllegalArgumentException( \"literal value cannot be null\" );\n\t\t\t}\n\t\t\treturn new SqmLiteralNull<>( this );\n\t\t}\n\t\telse {\n\t\t\treturn new SqmLiteral<>( value, resolveExpressible( getParameterBindType( value ) ), this );\n\t\t}\n\t}\n\n\t@Nonnull\n\t@Override\n\tpublic <N extends Number & Comparable<N>> SqmNumericExpression<N> numericLiteral(@Nonnull N value) {\n\t\treturn new SqmNumericExpressionWrapper<>( literal( value ) );\n\t}\n\n\t@Nonnull\n\t@Override\n\tpublic TextExpression stringLiteral(@Nonnull String value) {\n\t\treturn new SqmTextExpressionWrapper( literal( value ) );","sourceCodeStart":1945,"sourceCodeEnd":1981,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmCriteriaNodeBuilder.java#L1945-L1981","documentation":"criteriaBuilder.literal(null) is a non-standard convenience: by default Hibernate returns an SqmLiteralNull, but when JPA query compliance is enabled (hibernate.jpa.compliance.query=true, or Jakarta persistence compliance settings that imply it) Hibernate enforces the spec, where literal(null) is undefined, and throws IllegalArgumentException. The compliance flag makes Hibernate reject the call instead of silently producing its dialect extension.","triggerScenarios":"cb.literal(someNullableValue) where someNullableValue evaluates to null while hibernate.jpa.jpaComplianceQuery=true (AvailableSettings.JPA_QUERY_COMPLIANCE); test suites that enable full JPA compliance globally (hibernate.jpa.compliance=true) and then build IS NULL predicates via literal(null).","commonSituations":"Setting jakarta.persistence or hibernate.jpa.compliance properties to true for certification-style strictness and then reusing Hibernate-idiomatic literal(null) code; upgrading apps where compliance defaults changed; generic predicate builders that funnel every constant through literal().","solutions":["Use the spec-typed null: cb.nullLiteral(String.class) (or the wanted type) instead of cb.literal(null).","For IS NULL comparisons just call cb.isNull(path)/cb.isNotNull(path) rather than comparing against a null literal.","Only if you deliberately want Hibernate's lenient behavior: set hibernate.jpa.compliance.query=false and document the deviation."],"exampleFix":"// before\nPredicate p = cb.equal(order.get(\"shippedAt\"), cb.literal(maybeNull)); // maybeNull == null + JPA compliance on\n\n// after\nPredicate p = maybeNull == null\n        ? cb.isNull(order.get(\"shippedAt\"))\n        : cb.equal(order.get(\"shippedAt\"), cb.literal(maybeNull));\n// or, when a typed null expression is required:\nExpression<String> nullExpr = cb.nullLiteral(String.class);","handlingStrategy":"validation","validationCode":"Expression<T> safeLiteral(CriteriaBuilder cb, T value, Class<T> type) {\n    return value == null ? cb.nullLiteral(type) : cb.literal(value);\n}","typeGuard":null,"tryCatchPattern":"try {\n    e = cb.literal(nullable);\n} catch (IllegalArgumentException ex) {\n    if (\"literal value cannot be null\".equals(ex.getMessage())) e = cb.nullLiteral(expectedType);\n    else throw ex;\n}","preventionTips":["Never route possibly-null constants through literal(); branch to isNull/isNotNull or nullLiteral(Class).","Enable hibernate.jpa.compliance.query in tests if you enable it in production, so literal(null) misuse surfaces early.","Wrap literal creation in one helper (as above) used by all predicate builders."],"tags":["hibernate","criteria","literal","jpa-compliance","null"],"backgroundTag":"null-literal-in-query","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}