{"record":{"id":"0f8fe10a35e45f61","repo":"hibernate/hibernate-orm","slug":"provided-key-does-not-support-instance-identity","errorCode":null,"errorMessage":"Provided key does not support instance identity","messagePattern":"Provided key does not support instance identity","errorType":"exception","errorClass":"ClassCastException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityMap.java","lineNumber":74,"sourceCode":"\t * @return {@code true} if this map contains a mapping for the specified instance id\n\t * @implNote This method accesses the backing array with the provided instance id, but performs an instance\n\t * equality check ({@code ==}) with the provided key to ensure it corresponds to the mapped one\n\t */\n\tpublic boolean containsKey(int instanceId, Object key) {\n\t\treturn get( instanceId, key ) != null;\n\t}\n\n\t/**\n\t * {@inheritDoc}\n\t * @implNote This only works for {@link InstanceIdentity} keys, and it's inefficient\n\t * since we need to do a type check. Prefer using {@link #containsKey(int, Object)}.\n\t */\n\t@Override\n\tpublic boolean containsKey(Object key) {\n\t\tif ( key instanceof InstanceIdentity instance ) {\n\t\t\treturn containsKey( instance.$$_hibernate_getInstanceId(), instance );\n\t\t}\n\t\tthrow new ClassCastException( \"Provided key does not support instance identity\" );\n\t}\n\n\t@Override\n\tpublic boolean containsValue(Object value) {\n\t\tfor ( V v : values() ) {\n\t\t\tif ( Objects.equals( value, v ) ) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n\n\t/**\n\t * Tests if the specified key-value mapping is in the map.\n\t *\n\t * @param key possible key, must be an instance of {@link InstanceIdentity}\n\t * @param value possible value\n\t * @return {@code true} if and only if the specified key-value mapping is in the map","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityMap.java#L56-L92","documentation":"InstanceIdentityMap addresses entries by an integer instance id injected by Hibernate bytecode enhancement ($$_hibernate_getInstanceId from the InstanceIdentity interface). The java.util.Map-compatibility overload containsKey(Object) only works when the passed key implements InstanceIdentity; any other object (an id value, an unenhanced POJO, a String) is rejected with ClassCastException rather than returning a wrong answer.","triggerScenarios":"instanceIdentityMap.containsKey(someId) where someId is a String/Long/database id; containsKey(entityInstance) where the entity class was not bytecode-enhanced; passing a detached copy or a different object than the managed instance.","commonSituations":"Treating persistence-context-internal maps as ordinary Maps and probing them with identifiers instead of entity instances; using entity classes with enhancement disabled (plain POJOs never implement InstanceIdentity).","solutions":["Probe with the entity instance itself, and the same managed instance the map holds","Prefer the id-based overload containsKey(int instanceId, Object key)","Ensure the entity is bytecode-enhanced if you must use instance-identity collections","If you do not need identity addressing, use a plain HashMap keyed by business id"],"exampleFix":"// before: probing with a database id\nboolean loaded = map.containsKey( orderId );\n// after: probe with the enhanced entity instance\nboolean loaded = order instanceof InstanceIdentity i\n        ? map.containsKey( i.$$_hibernate_getInstanceId(), order )\n        : false;","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean usableAsInstanceIdentityKey(Object key) {\n    return key instanceof org.hibernate.engine.spi.InstanceIdentity;\n}","tryCatchPattern":null,"preventionTips":["Always probe with the managed entity instance, never with an id value","Prefer the int-overloads: containsKey(instanceId, key), get(instanceId, key)","Verify at startup that entity classes implement InstanceIdentity (enhancement applied)"],"tags":["hibernate","class-cast","instance-identity","bytecode-enhancement","collections"],"backgroundTag":"wrong-type-argument","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}