{"record":{"id":"735a1f995f270e88","repo":"hibernate/hibernate-orm","slug":"unsupported-literal-literal","errorCode":null,"errorMessage":"Unsupported literal: ${literal}","messagePattern":"Unsupported literal: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java","lineNumber":1992,"sourceCode":"\tpublic SqmExpression<?> visitParameterOrNumberLiteral(HqlParser.ParameterOrNumberLiteralContext ctx) {\n\t\tif ( ctx.INTEGER_LITERAL() != null ) {\n\t\t\treturn integerLiteral( ctx.INTEGER_LITERAL().getText() );\n\t\t}\n\t\telse if ( ctx.FLOAT_LITERAL() != null ) {\n\t\t\treturn floatLiteral( ctx.FLOAT_LITERAL().getText() );\n\t\t}\n\t\telse if ( ctx.DOUBLE_LITERAL() != null ) {\n\t\t\treturn doubleLiteral( ctx.DOUBLE_LITERAL().getText() );\n\t\t}\n\t\telse if ( ctx.parameter() != null ) {\n\t\t\treturn (SqmExpression<?>) ctx.parameter().accept( this );\n\t\t}\n\t\telse if ( ctx.getChild( 0 ) instanceof TerminalNode firstChild ) {\n\t\t\treturn switch ( firstChild.getSymbol().getType() ) {\n\t\t\t\tcase HqlParser.INTEGER_LITERAL -> integerLiteral( ctx.getChild( 0 ).getText() );\n\t\t\t\tcase HqlParser.FLOAT_LITERAL -> floatLiteral( ctx.getChild( 0 ).getText() );\n\t\t\t\tcase HqlParser.DOUBLE_LITERAL -> doubleLiteral( ctx.getChild( 0 ).getText() );\n\t\t\t\tdefault -> throw new UnsupportedOperationException( \"Unsupported literal: \" + ctx.getChild( 0 ).getText() );\n\t\t\t};\n\t\t}\n\t\telse {\n\t\t\treturn (SqmExpression<?>) ctx.getChild( 0 ).accept( this );\n\t\t}\n\t}\n\n\tpublic String getEntityName(HqlParser.EntityNameContext parserEntityName) {\n\t\tfinal var entityName = new StringBuilder();\n\t\tfinal var identifierList = parserEntityName.identifier();\n\t\tfinal int size = identifierList.size();\n\t\tfor ( int i = 0; i < size; i++ ) {\n\t\t\tfinal var id = identifierList.get( i );\n\t\t\tif ( i > 0) {\n\t\t\t\tentityName.append( '.' );\n\t\t\t}\n\t\t\tentityName.append( visitIdentifier( id ) );\n\t\t}","sourceCodeStart":1974,"sourceCodeEnd":2010,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java#L1974-L2010","documentation":"The literal visitor only translates a fixed set of terminal token types (INTEGER_LITERAL, FLOAT_LITERAL, DOUBLE_LITERAL in this switch, after earlier branches handled other literal categories, parameters and nested expressions). Reaching the default arm means the parser produced a literal token the semantic builder does not handle - an unsupported literal syntax or a grammar/visitor mismatch, i.e. an internal limitation rather than a user mapping problem.","triggerScenarios":"Inline literals with unusual token forms (e.g. hexadecimal/octal-style numeric literals) that parse into an unhandled terminal node; version mixes where the grammar emits token types this visitor build does not translate.","commonSituations":"Copying native SQL literals into HQL; running hibernate-core versions with a parser/visitor gap; genuine Hibernate bugs after a grammar change (check the HHH JIRA before debugging your own mapping).","solutions":["Rewrite the literal in a plain supported form (decimal number, quoted string, date/time literal)","Bind the value as a query parameter instead of inlining it","Upgrade hibernate-core to the latest patch release in case the literal form is now supported","If it still reproduces, report it to Hibernate (HHH JIRA) with the exact literal text"],"exampleFix":"// before\nselect p from Payment p where p.amount > 0x1F\n\n// after\nselect p from Payment p where p.amount > :minAmount  // bind 31 as parameter","handlingStrategy":"validation","validationCode":"// Lint HQL for literal forms Hibernate does not translate (hex, octal)\nstatic boolean hasUnsupportedLiteral(String hql) {\n    return java.util.regex.Pattern.compile(\"\\\\b0[xX][0-9a-fA-F]+\").matcher(hql).find();\n}","typeGuard":null,"tryCatchPattern":"try {\n    return em.createQuery(hql, Payment.class).getResultList();\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unsupported literal\")) {\n        throw new IllegalArgumentException(\"Rewrite the literal as a parameter or decimal: \" + hql, e);\n    }\n    throw e;\n}","preventionTips":["Bind values as parameters instead of inlining exotic literal syntax","Keep hibernate-core grammar and visitor in sync by upgrading whole artifacts, never mixing versions","Report reproducible cases to the HHH JIRA with the literal text"],"tags":["hql","literal","parser","hibernate","internal-error"],"backgroundTag":"unsupported-literal-syntax","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}