{"record":{"id":"e35a07e9e11ca37d","repo":"hibernate/hibernate-orm","slug":"named-query-hint-hintname-is-not-an-inte","errorCode":null,"errorMessage":"Named query hint [\" + hintName + \"] is not an integer: \" + queryName","messagePattern":"Named query hint \\[\" \\+ hintName \\+ \"\\] is not an integer: \" \\+ queryName","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java","lineNumber":95,"sourceCode":"\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}\n\t\tcatch (Exception e) {\n\t\t\tthrow new AnnotationException( \"Named query hint [\" + hintName + \"] is not an integer: \" + queryName, e );\n\t\t}\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Specialized access\n\n\t@Nullable\n\tpublic Integer getTimeout() {\n\t\tfinal Integer jakartaTimeout = getInteger( SpecHints.HINT_SPEC_QUERY_TIMEOUT );\n\t\tif ( jakartaTimeout != null ) {\n\t\t\t// convert milliseconds to seconds\n\t\t\treturn (int) Math.round( jakartaTimeout.doubleValue() / 1000.0 );\n\t\t}\n\n\t\tfinal Integer javaeeTimeout = getInteger( LegacySpecHints.HINT_JAVAEE_QUERY_TIMEOUT );\n\t\tif ( javaeeTimeout != null ) {\n\t\t\t// convert milliseconds to seconds","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java#L77-L113","documentation":"QueryHintDefinition.getInteger parses an integer hint (e.g. the Jakarta timeout hint or Hibernate fetch-size style hints) with ConfigurationHelper.getInteger; unparseable values throw and get wrapped in AnnotationException naming the hint and query. The failure occurs while the named query definition is built at bootstrap.","triggerScenarios":"@QueryHint(name = \"jakarta.persistence.query.timeout\", value = \"10s\") or \"1_000\" or an empty string — anything Integer.parseInt-style parsing rejects; also numeric hints whose keys are misrouted. Fires during binding of @NamedQuery/@NamedNativeQuery definitions.","commonSituations":"Writing timeout with a unit suffix (\"30s\") instead of plain milliseconds; copying Hibernate's own timeout (which wants seconds via org.hibernate.timeout) into the Jakarta millisecond hint; YAML/property values carrying spaces or units; misspelled hint keys colliding with numeric readers.","solutions":["Supply plain digits: jakarta.persistence.query.timeout is milliseconds (\"30000\"), org.hibernate.timeout is seconds (\"30\").","Strip units/spaces from configuration-sourced hint values before use.","Double-check the hint key: the right unit depends on whether you use the Jakarta or the Hibernate timeout hint."],"exampleFix":"// before\n@QueryHint(name = \"jakarta.persistence.query.timeout\", value = \"30s\")\n\n// after\n@QueryHint(name = \"jakarta.persistence.query.timeout\", value = \"30000\") // 30s in ms","handlingStrategy":"validation","validationCode":"@Test void numericHintsAreDigits() {\n    for (QueryHint h : collectHints()) {\n        if (NUMERIC_HINTS.contains(h.name()))\n            assertTrue(h.value().chars().allMatch(Character::isDigit),\n                h.name() + \" must be a plain number, was: \" + h.value());\n    }\n}","typeGuard":"boolean isPlainInteger(String v) { return v != null && v.chars().allMatch(Character::isDigit); }","tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) {\n    failBuild(\"Bad integer hint (check ms vs s units): \" + e.getMessage());\n}","preventionTips":["jakarta timeout hint is milliseconds, org.hibernate.timeout is seconds - never suffix units.","Validate config-sourced numeric hints for digits/spaces before shipping."],"tags":["hibernate","orm","query-hints","integer-parsing","timeout","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"}