{"record":{"id":"0b1255d7c55b83a3","repo":"hibernate/hibernate-orm","slug":"instance-id-must-be-a-positive-value","errorCode":null,"errorMessage":"Instance ID must be a positive value","messagePattern":"Instance ID must be a positive value","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityMap.java","lineNumber":153,"sourceCode":"\t * since we need to do a type check. Prefer using {@link #get(int, Object)}.\n\t */\n\t@Override\n\tpublic @Nullable V get(Object key) {\n\t\tif ( key instanceof InstanceIdentity instance ) {\n\t\t\treturn get( 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 @Nullable V put(K key, V value) {\n\t\tif ( key == null ) {\n\t\t\tthrow new NullPointerException( \"This map does not support null keys\" );\n\t\t}\n\n\t\tfinal int index = key.$$_hibernate_getInstanceId() - 1;\n\t\tif ( index < 0 ) {\n\t\t\tthrow new IllegalArgumentException( \"Instance ID must be a positive value\" );\n\t\t}\n\n\t\tfinal Map.Entry<K, V> old = set( index, new AbstractMap.SimpleImmutableEntry<>( key, value ) );\n\t\tif ( old == null ) {\n\t\t\tsize++;\n\t\t\treturn null;\n\t\t}\n\t\telse {\n\t\t\treturn old.getValue();\n\t\t}\n\t}\n\n\t/**\n\t * Removes the mapping for an instance id from this map if it is present (optional operation).\n\t *\n\t * @param instanceId the instance id whose associated value is to be returned\n\t * @param key key instance to double-check instance equality\n\t * @return the previous value associated with {@code instanceId}, or {@code null} if there was no mapping for it.","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityMap.java#L135-L171","documentation":"put() computes the storage index as key.$$_hibernate_getInstanceId() - 1. An id of 0 (or negative) yields index < 0 and this IllegalArgumentException. Id 0 means the enhancement runtime never assigned an instance id — classically because the entity class is not bytecode-enhanced, or the instance has not yet been registered where ids get assigned.","triggerScenarios":"put(pojoEntity, value) where the entity class lacks enhancement so $$_hibernate_getInstanceId() returns 0; putting a freshly created entity before it became managed/enhanced.","commonSituations":"Using InstanceIdentityMap/related structures with plain POJOs in tests; enhancement disabled in the build (plugin not applied) while runtime code assumes it; dev-time classpath where enhanced and unenhanced versions mix.","solutions":["Enable Hibernate bytecode enhancement for the entity classes (Maven/Gradle enhancer plugin or agent)","Only put instances that are already managed — with a positive assigned instance id","If enhancement is off by design, use a regular HashMap instead of instance-identity collections","Verify at startup that entity classes implement org.hibernate.engine.spi.InstanceIdentity"],"exampleFix":"// before\nmap.put( entity, state ); // entity not enhanced -> id 0 -> throws\n// after\nif ( entity instanceof InstanceIdentity i && i.$$_hibernate_getInstanceId() > 0 ) {\n    map.put( entity, state );\n}\nelse {\n    fallbackMap.put( entity.getId(), state );\n}","handlingStrategy":"validation","validationCode":"if ( key instanceof org.hibernate.engine.spi.InstanceIdentity id\n        && id.$$_hibernate_getInstanceId() > 0 ) {\n    map.put( key, value );\n} else {\n    throw new IllegalStateException( \"entity not enhanced or not managed: \" + key.getClass() );\n}","typeGuard":"static boolean hasAssignedInstanceId(Object entity) {\n    return entity instanceof org.hibernate.engine.spi.InstanceIdentity id\n            && id.$$_hibernate_getInstanceId() > 0;\n}","tryCatchPattern":null,"preventionTips":["Apply Hibernate bytecode enhancement in the build for entity classes used with instance-identity collections","Insert only managed instances (assigned ids), never fresh transients","Add a startup check that entity classes implement InstanceIdentity"],"tags":["hibernate","instance-id","bytecode-enhancement","validation","instance-identity"],"backgroundTag":"missing-bytecode-enhancement","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}