hibernate/hibernate-orm · error · IllegalArgumentException

Native lock-mode hint [%s] must specify %s or %s. Encountere

Error message

Native lock-mode hint [%s] must specify %s or %s. Encountered type: %s

What it means

Thrown by applyLockModeHint(String hintName, Object value) when the value of the 'org.hibernate.lockMode' hint (or the legacy alias-specific form 'org.hibernate.lockMode.<alias>' matched by hintName.startsWith in the switch's default branch) is not one of the three accepted types: org.hibernate.LockMode, jakarta.persistence.LockModeType, or a String in LockMode external form (e.g. "OPTIMISTIC", "PESSIMISTIC_WRITE"). The message lists LockMode.class and LockModeType.class names and the offending value's class.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java:723

	}


	private void applyGraph(RootGraphImplementor<?> entityGraph, GraphSemantic graphSemantic) {
		queryOptions.applyGraph( entityGraph, graphSemantic );
	}

	private void applyLockModeHint(String hintName, Object value) {
		if ( value instanceof LockMode lockMode ) {
			applyLockModeHint( hintName, lockMode );
		}
		else if ( value instanceof LockModeType lockModeType ) {
			applyLockModeHint( hintName, LockMode.fromJpaLockMode( lockModeType ) );
		}
		else if ( value instanceof String string ) {
			applyLockModeHint( hintName, LockMode.fromExternalForm( string ) );
		}
		else {
			throw new IllegalArgumentException(
					String.format(
							"Native lock-mode hint [%s] must specify %s or %s. Encountered type: %s",
							HINT_NATIVE_LOCK_MODE,
							LockMode.class.getName(),
							LockModeType.class.getName(),
							value.getClass().getName()
					)
			);
		}
	}

	protected void applyLockModeHint(String hintName, LockMode value) {
		//noinspection removal
		queryOptions.getLockOptions().setLockMode( value );
	}

	protected void applyLockTimeoutHint(String hintName, Object timeout) {
		//noinspection removal

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass the Hibernate enum: setHint(HibernateHints.HINT_NATIVE_LOCK_MODE, LockMode.PESSIMISTIC_WRITE)
2. Or the JPA enum: LockModeType.PESSIMISTIC_WRITE, or its exact String name "PESSIMISTIC_WRITE"
3. For per-alias lock modes keep the 'org.hibernate.lockMode.<alias>' key but the same value types
4. Ensure only one persistence API version (jakarta, not javax+ jakarta) is on the classpath

Example fix

// before
query.setHint( "org.hibernate.lockMode.o", 5000 ); // int is not LockMode/LockModeType/String

// after
query.setHint( "org.hibernate.lockMode.o", LockModeType.PESSIMISTIC_WRITE );
// timeout belongs to a different hint:
query.setHint( SpecHints.HINT_SPEC_LOCK_TIMEOUT, 5000 );

Object v = hintValue;
boolean ok = v instanceof org.hibernate.LockMode
        || v instanceof jakarta.persistence.LockModeType
        || v instanceof String;
if ( !ok ) throw new IllegalArgumentException( "Lock-mode hint needs LockMode/LockModeType/String" );
query.setHint( HibernateHints.HINT_NATIVE_LOCK_MODE, v );

static boolean isLockModeHintValue(Object v) {
    return v instanceof org.hibernate.LockMode
        || v instanceof jakarta.persistence.LockModeType
        || v instanceof String;
}

When it happens

Trigger: query.setHint("org.hibernate.lockMode", 5000) — passing the numeric lock timeout copied from 'jakarta.persistence.lock.timeout' code. Passing a Boolean, an enum constant of the wrong type (java.sql or a custom enum), or a jakarta LockModeType on a path where the classloader/provider mismatch makes instanceof fail. Alias-specific hints: setHint("org.hibernate.lockMode.o", new Object()).

Common situations: Copy-pasting lock-timeout hint code and changing only the key; upgrading javax.persistence→jakarta.persistence and having both LockModeType classes on the classpath so the instanceof checks the wrong one; legacy Hibernate 3-style alias lockmode maps converted to hints with original values.

Related errors

• WRITE is not a valid LockMode as an argument
• Lock mode ${lockMode} not valid for locking via 'update' sta
• Entity '{}' may not be locked at level {}
• Entity '{}' may not be locked at level {}
• Entity '{}' may not be locked at level {}

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