{"record":{"id":"d25eacc1b25338cf","repo":"hibernate/hibernate-orm","slug":"named-query-hint-hintname-is-not-a-boole","errorCode":null,"errorMessage":"Named query hint [\" + hintName + \"] is not a boolean: \" + queryName","messagePattern":"Named query hint \\[\" \\+ hintName \\+ \"\\] is not a boolean: \" \\+ queryName","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java","lineNumber":75,"sourceCode":"\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Generic access\n\n\t@Nonnull\n\tpublic Map<String, Object> getHintsMap() {\n\t\treturn hintsMap;\n\t}\n\n\t@Nullable\n\tpublic String getString(@Nonnull String hintName) {\n\t\treturn (String) hintsMap.get( hintName );\n\t}\n\n\tpublic boolean getBoolean(@Nonnull String hintName) {\n\t\ttry {\n\t\t\treturn ConfigurationHelper.getBoolean( hintName, hintsMap );\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new AnnotationException( \"Named query hint [\" + hintName + \"] is not a boolean: \" + queryName, e );\n\t\t}\n\t}\n\n\t@Nullable\n\tpublic Boolean getBooleanWrapper(@Nonnull String hintName) {\n\t\ttry {\n\t\t\treturn ConfigurationHelper.getBooleanWrapper( hintName, hintsMap, null );\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new AnnotationException( \"Named query hint [\" + hintName + \"] is not a boolean: \" + queryName, e );\n\t\t}\n\t}\n\n\t@Nullable\n\tpublic Integer getInteger(@Nonnull String hintName) {\n\t\ttry {\n\t\t\treturn ConfigurationHelper.getInteger( hintName, hintsMap );\n\t\t}","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java#L57-L93","documentation":"QueryHintDefinition.getBoolean reads a hint from the named query's hintsMap via ConfigurationHelper.getBoolean; if the stored value cannot be interpreted as a boolean it throws, and QueryHintDefinition wraps it in AnnotationException naming the hint and query. This happens while named-query definitions are initialized at bootstrap, not when the query runs.","triggerScenarios":"A boolean hint such as org.hibernate.cacheable or org.hibernate.readOnly on @NamedQuery/@QueryHint with a value ConfigurationHelper cannot parse, e.g. \"yes\", \"1\" (depends on parser), or a misspelled string; jakarta.persistence.query.timeout-style numeric strings routed to a boolean getter would also fail.","commonSituations":"Writing @QueryHint(name = \"org.hibernate.cacheable\", value = \"yes\"); copying hint examples with Y/N conventions from other stacks; passing property-file values (on/off) that the boolean parser rejects; typos like \"ture\".","solutions":["Use literal \"true\" or \"false\" for boolean hints.","Check the exact hint key — a misspelled name can route a non-boolean value into a boolean slot.","If hints come from configuration, normalize them to true/false before they reach the mapping."],"exampleFix":"// before\n@NamedQuery(\n    name = \"Person.findActive\",\n    query = \"from Person p where p.active = true\",\n    hints = @QueryHint(name = \"org.hibernate.cacheable\", value = \"yes\"))\n\n// after\n@NamedQuery(\n    name = \"Person.findActive\",\n    query = \"from Person p where p.active = true\",\n    hints = @QueryHint(name = \"org.hibernate.cacheable\", value = \"true\"))","handlingStrategy":"validation","validationCode":"// test-time: validate every declared boolean hint parses\nfor (NamedQuery q : allNamedQueries()) {\n    for (QueryHint h : q.hints()) {\n        if (isBooleanHint(h.name())) {\n            Boolean.parseBoolean(h.value()); // throws nothing on bad input, so assert explicitly:\n            assertTrue(h.value().equals(\"true\") || h.value().equals(\"false\"),\n                h.name() + \" must be true/false, was: \" + h.value());\n        }\n    }\n}","typeGuard":"boolean isValidBooleanHint(String value) {\n    return \"true\".equalsIgnoreCase(value) || \"false\".equalsIgnoreCase(value);\n}","tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) { // wraps the underlying parse failure, names hint + query\n    failBuild(\"Bad boolean query hint: \" + e.getMessage() + \" cause=\" + e.getCause());\n}","preventionTips":["Only \"true\"/\"false\" for boolean hints - never yes/no/on/off.","Keep hint keys in constants to avoid misspellings landing in the wrong parser.","Add a hint lint step to the mapping test suite."],"tags":["hibernate","orm","query-hints","boolean-parsing","named-query"],"backgroundTag":"query-hint-invalid-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}