{"record":{"id":"d400851b5f2d333b","repo":"hibernate/hibernate-orm","slug":"instance-id-must-be-a-positive-value-d40085","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/InstanceIdentityStore.java","lineNumber":84,"sourceCode":"\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\treturn null;\n\t}\n\n\t/**\n\t * Associates the specified value with the specified key in this store (optional operation). If the store\n\t * previously contained a mapping for the key, the old value is replaced by the specified value.\n\t *\n\t * @param key key with which the specified value is to be associated\n\t * @param value value to be associated with the specified key\n\t */\n\tpublic void put(Object key, int instanceId, V value) {\n\t\tif ( key == null ) {\n\t\t\tthrow new NullPointerException( \"This store does not support null keys\" );\n\t\t}\n\t\telse if ( instanceId <= 0 ) {\n\t\t\tthrow new IllegalArgumentException( \"Instance ID must be a positive value\" );\n\t\t}\n\n\t\tfinal int keyIndex = toKeyIndex( instanceId );\n\t\tfinal Page<Object> page = getOrCreateEntryPage( keyIndex );\n\t\tfinal int pageOffset = toPageOffset( keyIndex );\n\t\tpage.set( pageOffset, key );\n\t\tpage.set( pageOffset + 1, value );\n\t}\n\n\t/**\n\t * Removes the mapping for an instance id from this store 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 * @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 void remove(int instanceId, Object key) {","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/util/collections/InstanceIdentityStore.java#L66-L102","documentation":"InstanceIdentityStore.put(Object key, int instanceId, V value) requires instanceId > 0 and throws IllegalArgumentException otherwise. The id is assigned by Hibernate bytecode enhancement when an instance first touches a persistence context; id 0 (the unset value) means the class was not enhanced or the instance was never registered — so the store refuses to address slot -1/0-derived indexes with an unassigned id.","triggerScenarios":"put(entity, 0, value) with an unenhanced entity class ($$_hibernate_getInstanceId() returns 0); putting a transient instance before it became managed; passing a manually computed id that is <= 0.","commonSituations":"Bytecode enhancement disabled or missing from the build while code assumes enhanced entities; test fixtures instantiating entities directly and inserting them into persistence-context-adjacent stores; mixed enhanced/unenhanced classes after a build change.","solutions":["Run the Hibernate bytecode enhancer over the entity classes (Maven/Gradle plugin or runtime agent)","Only store instances that already have an assigned id — i.e. after they became managed","Guard the call: skip or fall back when $$_hibernate_getInstanceId() <= 0"],"exampleFix":"// before\nstore.put( entity, entity.$$_hibernate_getInstanceId(), value );\n// after\nint id = entity.$$_hibernate_getInstanceId();\nif ( id > 0 ) {\n    store.put( entity, id, value );\n}\nelse {\n    throw new IllegalStateException( \"entity class not enhanced: \" + entity.getClass() );\n}","handlingStrategy":"validation","validationCode":"if ( instanceId <= 0 ) {\n    throw new IllegalStateException( \"instance id not assigned (unenhanced or unmanaged class): \" + key.getClass().getName() );\n}\nstore.put( key, instanceId, value );","typeGuard":"static boolean hasAssignedInstanceId(Object entity, int instanceId) {\n    return entity != null && instanceId > 0;\n}","tryCatchPattern":null,"preventionTips":["Run the Hibernate bytecode enhancer over entity classes in every build path (main + tests)","Only store instances after they become managed and receive an instance id","Guard against id 0 as 'unset' wherever you touch enhancement-generated ids"],"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"}