hibernate/hibernate-orm · error · AnnotationException

Named query hint [" + hintName + "] is not an integer: " + q

Error message

Named query hint [" + hintName + "] is not an integer: " + queryName

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java:95

	}

	@Nullable
	public Boolean getBooleanWrapper(@Nonnull String hintName) {
		try {
			return ConfigurationHelper.getBooleanWrapper( hintName, hintsMap, null );
		}
		catch (Exception e) {
			throw new AnnotationException( "Named query hint [" + hintName + "] is not a boolean: " + queryName, e );
		}
	}

	@Nullable
	public Integer getInteger(@Nonnull String hintName) {
		try {
			return ConfigurationHelper.getInteger( hintName, hintsMap );
		}
		catch (Exception e) {
			throw new AnnotationException( "Named query hint [" + hintName + "] is not an integer: " + queryName, e );
		}
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Specialized access

	@Nullable
	public Integer getTimeout() {
		final Integer jakartaTimeout = getInteger( SpecHints.HINT_SPEC_QUERY_TIMEOUT );
		if ( jakartaTimeout != null ) {
			// convert milliseconds to seconds
			return (int) Math.round( jakartaTimeout.doubleValue() / 1000.0 );
		}

		final Integer javaeeTimeout = getInteger( LegacySpecHints.HINT_JAVAEE_QUERY_TIMEOUT );
		if ( javaeeTimeout != null ) {
			// convert milliseconds to seconds

View on GitHub (pinned to fad1729dce)

Solutions

1. Supply plain digits: jakarta.persistence.query.timeout is milliseconds ("30000"), org.hibernate.timeout is seconds ("30").
2. Strip units/spaces from configuration-sourced hint values before use.
3. Double-check the hint key: the right unit depends on whether you use the Jakarta or the Hibernate timeout hint.

Example fix

// before
@QueryHint(name = "jakarta.persistence.query.timeout", value = "30s")

// after
@QueryHint(name = "jakarta.persistence.query.timeout", value = "30000") // 30s in ms

@Test void numericHintsAreDigits() {
    for (QueryHint h : collectHints()) {
        if (NUMERIC_HINTS.contains(h.name()))
            assertTrue(h.value().chars().allMatch(Character::isDigit),
                h.name() + " must be a plain number, was: " + h.value());
    }
}

boolean isPlainInteger(String v) { return v != null && v.chars().allMatch(Character::isDigit); }

try {
    metadata = sources.buildMetadata();
} catch (AnnotationException e) {
    failBuild("Bad integer hint (check ms vs s units): " + e.getMessage());
}

When it happens

Trigger: @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.

Common situations: 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.

Related errors

• Named query hint [" + hintName + "] is not a boolean: " + qu
• Unable to interpret CacheMode in named query hint: " + query
• Named query definition is null
• Named query definition name is null: %s
• Duplicate named query '%s'

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/e35a07e9e11ca37d. Report an issue: GitHub.