{"record":{"id":"335e09d7e40857f3","repo":"hibernate/hibernate-orm","slug":"native-lock-mode-hint-s-must-specify-s-or-s","errorCode":null,"errorMessage":"Native lock-mode hint [%s] must specify %s or %s. Encountered type: %s","messagePattern":"Native lock-mode hint \\[(.+?)\\] must specify (.+?) or (.+?)\\. Encountered type: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":723,"sourceCode":"\t}\n\n\n\tprivate void applyGraph(RootGraphImplementor<?> entityGraph, GraphSemantic graphSemantic) {\n\t\tqueryOptions.applyGraph( entityGraph, graphSemantic );\n\t}\n\n\tprivate void applyLockModeHint(String hintName, Object value) {\n\t\tif ( value instanceof LockMode lockMode ) {\n\t\t\tapplyLockModeHint( hintName, lockMode );\n\t\t}\n\t\telse if ( value instanceof LockModeType lockModeType ) {\n\t\t\tapplyLockModeHint( hintName, LockMode.fromJpaLockMode( lockModeType ) );\n\t\t}\n\t\telse if ( value instanceof String string ) {\n\t\t\tapplyLockModeHint( hintName, LockMode.fromExternalForm( string ) );\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\"Native lock-mode hint [%s] must specify %s or %s. Encountered type: %s\",\n\t\t\t\t\t\t\tHINT_NATIVE_LOCK_MODE,\n\t\t\t\t\t\t\tLockMode.class.getName(),\n\t\t\t\t\t\t\tLockModeType.class.getName(),\n\t\t\t\t\t\t\tvalue.getClass().getName()\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n\t}\n\n\tprotected void applyLockModeHint(String hintName, LockMode value) {\n\t\t//noinspection removal\n\t\tqueryOptions.getLockOptions().setLockMode( value );\n\t}\n\n\tprotected void applyLockTimeoutHint(String hintName, Object timeout) {\n\t\t//noinspection removal","sourceCodeStart":705,"sourceCodeEnd":741,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L705-L741","documentation":"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.","triggerScenarios":"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()).","commonSituations":"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.","solutions":["Pass the Hibernate enum: setHint(HibernateHints.HINT_NATIVE_LOCK_MODE, LockMode.PESSIMISTIC_WRITE)","Or the JPA enum: LockModeType.PESSIMISTIC_WRITE, or its exact String name \"PESSIMISTIC_WRITE\"","For per-alias lock modes keep the 'org.hibernate.lockMode.<alias>' key but the same value types","Ensure only one persistence API version (jakarta, not javax+ jakarta) is on the classpath"],"exampleFix":"// before\nquery.setHint( \"org.hibernate.lockMode.o\", 5000 ); // int is not LockMode/LockModeType/String\n\n// after\nquery.setHint( \"org.hibernate.lockMode.o\", LockModeType.PESSIMISTIC_WRITE );\n// timeout belongs to a different hint:\nquery.setHint( SpecHints.HINT_SPEC_LOCK_TIMEOUT, 5000 );","handlingStrategy":"validation","validationCode":"Object v = hintValue;\nboolean ok = v instanceof org.hibernate.LockMode\n        || v instanceof jakarta.persistence.LockModeType\n        || v instanceof String;\nif ( !ok ) throw new IllegalArgumentException( \"Lock-mode hint needs LockMode/LockModeType/String\" );\nquery.setHint( HibernateHints.HINT_NATIVE_LOCK_MODE, v );","typeGuard":"static boolean isLockModeHintValue(Object v) {\n    return v instanceof org.hibernate.LockMode\n        || v instanceof jakarta.persistence.LockModeType\n        || v instanceof String;\n}","tryCatchPattern":null,"preventionTips":["Keep lock-timeout (integer) and lock-mode (enum/string) hints in separate constants so they can't be swapped","Validate enum string values against LockMode.valueOf before passing them on","Keep a single JPA API generation (jakarta) on the classpath"],"tags":["hibernate","locking","lock-mode","query-hints","sethint"],"backgroundTag":"lock-mode-hint-invalid","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}