{"record":{"id":"a4539a75b4e9b561","repo":"hibernate/hibernate-orm","slug":"unable-to-interpret-lockmode-reference-from-incomi","errorCode":null,"errorMessage":"Unable to interpret LockMode reference from incoming external form: \" + externalForm","messagePattern":"Unable to interpret LockMode reference from incoming external form: \" \\+ externalForm","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/LockMode.java","lineNumber":324,"sourceCode":"\t\t};\n\t}\n\n\tpublic static LockMode fromExternalForm(String externalForm) {\n\t\tif ( externalForm == null ) {\n\t\t\treturn NONE;\n\t\t}\n\n\t\tfor ( LockMode lockMode : values() ) {\n\t\t\tif ( lockMode.toExternalForm().equalsIgnoreCase( externalForm ) ) {\n\t\t\t\treturn lockMode;\n\t\t\t}\n\t\t}\n\n\t\tif ( externalForm.equalsIgnoreCase( \"upgrade\" ) ) {\n\t\t\treturn PESSIMISTIC_WRITE;\n\t\t}\n\n\t\tthrow new IllegalArgumentException( \"Unable to interpret LockMode reference from incoming external form: \" + externalForm );\n\t}\n\n\t/**\n\t * @return an instance of {@link LockOptions} with this lock mode, and\n\t *         all other settings defaulted.\n\t *\n\t * @deprecated With no replacement; {@linkplain LockOptions} is no longer considered an API.\n\t */\n\t@Deprecated(since = \"7\", forRemoval = true)\n\tpublic LockOptions toLockOptions() {\n\t\treturn switch (this) {\n\t\t\tcase NONE -> new LockOptions();\n\t\t\tcase READ -> new LockOptions( READ );\n\t\t\tcase OPTIMISTIC -> new LockOptions( OPTIMISTIC );\n\t\t\tcase OPTIMISTIC_FORCE_INCREMENT -> new LockOptions( OPTIMISTIC_FORCE_INCREMENT );\n\t\t\tcase UPGRADE_NOWAIT -> new LockOptions( PESSIMISTIC_WRITE, NO_WAIT_MILLI, PessimisticLockScope.NORMAL, Locking.FollowOn.ALLOW );\n\t\t\tcase UPGRADE_SKIPLOCKED -> new LockOptions( PESSIMISTIC_WRITE, SKIP_LOCKED_MILLI, PessimisticLockScope.NORMAL, Locking.FollowOn.ALLOW );\n\t\t\tcase PESSIMISTIC_READ -> new LockOptions( PESSIMISTIC_READ );","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/LockMode.java#L306-L342","documentation":"LockMode.fromExternalForm(String) matches the incoming string case-insensitively against each LockMode's external form (the lowercased enum name, with underscores converted to hyphens for upgrade-nowait/upgrade-skiplocked) plus the legacy alias 'upgrade'. Any string that matches none of them - a typo, an old name, or free-form user input - throws IllegalArgumentException.","triggerScenarios":"Calling LockMode.fromExternalForm(\"pessimistic write\"), fromExternalForm(\"FORCE\"), or fromExternalForm(\"UPGRADE_NOWAIT\") (correct form is 'upgrade-nowait'). Typically the string comes from XML config, REST query parameters, or property files that name a lock mode.","commonSituations":"Parsing lock-mode strings from external configuration or user input; code migrating from Hibernate 5-era names (e.g. old 'FORCE' / underscore forms); whitespace or case variants slipping in ('READ ' with a trailing space).","solutions":["Use the exact external forms: none, read, write, optimistic, optimistic_force_increment, pessimistic_read, pessimistic_write, pessimistic_force_increment, upgrade-nowait, upgrade-skiplocked (legacy alias: upgrade).","Prefer passing LockMode constants directly instead of strings when the value is in your control.","Trim and normalize the string, and validate it against LockMode.values()/toExternalForm() before calling.","Catch IllegalArgumentException and fall back to a safe default (e.g. LockMode.NONE) for external input."],"exampleFix":"// before - underscore form never matches\nLockMode mode = LockMode.fromExternalForm(\"UPGRADE_NOWAIT\");\n\n// after - valid external form (hyphenated, case-insensitive)\nLockMode mode = LockMode.fromExternalForm(\"upgrade-nowait\");","handlingStrategy":"validation","validationCode":"static Optional<LockMode> tryParseLockMode(String raw) {\n    if (raw == null) return Optional.of(LockMode.NONE);\n    String s = raw.trim();\n    for (LockMode m : LockMode.values()) {\n        if (m.toExternalForm().equalsIgnoreCase(s)) return Optional.of(m);\n    }\n    if (s.equalsIgnoreCase(\"upgrade\")) return Optional.of(LockMode.PESSIMISTIC_WRITE);\n    return Optional.empty();\n}\n\nOptional<LockMode> mode = tryParseLockMode(input);\nLockMode lockMode = mode.orElseThrow(() -> new IllegalArgumentException(\"Unknown lock mode: \" + input));","typeGuard":"static boolean isValidLockModeExternalForm(String raw) {\n    return tryParseLockMode(raw).isPresent();\n}","tryCatchPattern":"try {\n    LockMode mode = LockMode.fromExternalForm(input);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Ignoring unknown lock mode '{}', defaulting to NONE\", input);\n    mode = LockMode.NONE; // never let free-form input crash request handling\n}","preventionTips":["Validate external lock-mode strings against LockMode.toExternalForm() values before parsing","Remember the hyphenated forms: upgrade-nowait, upgrade-skiplocked (not UPGRADE_NOWAIT)","Trim input strings; pass LockMode constants instead of strings whenever possible"],"tags":["locking","lock-mode","parsing","external-config","illegal-argument"],"backgroundTag":"invalid-enum-config-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}