{"record":{"id":"850afc6e9dbbb1cf","repo":"hibernate/hibernate-orm","slug":"queued-clear-cannot-be-used-with-orphan-delete-850afc","errorCode":null,"errorMessage":"queued clear cannot be used with orphan delete","messagePattern":"queued clear cannot be used with orphan delete","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentMap.java","lineNumber":613,"sourceCode":"\t@Override\n\tpublic boolean entryExists(Object entry, int i) {\n\t\treturn ( (Entry<?,?>) entry ).getValue() != null;\n\t}\n\n\tfinal class Clear implements DelayedOperation<E> {\n\t\t@Override\n\t\tpublic void operate() {\n\t\t\tmap.clear();\n\t\t}\n\n\t\t@Override\n\t\tpublic E getAddedInstance() {\n\t\t\treturn null;\n\t\t}\n\n\t\t@Override\n\t\tpublic E getOrphan() {\n\t\t\tthrow new UnsupportedOperationException( \"queued clear cannot be used with orphan delete\" );\n\t\t}\n\t}\n\n\tabstract class AbstractMapValueDelayedOperation extends AbstractValueDelayedOperation {\n\t\tprivate final K index;\n\n\t\tprotected AbstractMapValueDelayedOperation(K index, E addedValue, E orphan) {\n\t\t\tsuper( addedValue, orphan );\n\t\t\tthis.index = index;\n\t\t}\n\n\t\tprotected final K getIndex() {\n\t\t\treturn index;\n\t\t}\n\n\t\t@Override\n\t\tpublic Object getAddedEntry() {\n\t\t\treturn Map.entry( getIndex(), getAddedInstance() );","sourceCodeStart":595,"sourceCodeEnd":631,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/collection/spi/PersistentMap.java#L595-L631","documentation":"PersistentMap queues operations on an uninitialized lazy Map, so clear() on an uninitialized map becomes a queued Clear operation. A bulk Clear cannot enumerate which entries were removed, so when the association has orphan delete enabled (orphanRemoval=true / delete-orphan) and flush asks the queued operation for its orphan, getOrphan() throws UnsupportedOperationException. Map flavor of the same limitation as PersistentList.","triggerScenarios":"@OneToMany(orphanRemoval = true) @MapKeyColumn Map<String, Item> children; parent loaded without touching the map; children.clear() called; flush requires orphan deletion for the collection role.","commonSituations":"Keyed child collections replaced wholesale (clear + repopulate) in service-layer update methods; EAGER->LAZY mapping changes; merge/copy utilities clearing target maps; version upgrades that expose the queued path.","solutions":["Initialize the map before clearing: Hibernate.initialize(parent.getChildren()) or call size() first","Remove entries individually on the initialized map so each Remove carries its orphan","Drop orphanRemoval for map associations managed by clear-and-replace","Cover the update flow with a flush-performing test against the real mapping"],"exampleFix":"// before\nparent.getChildren().clear(); // uninitialized PersistentMap -> queued Clear\nparent.getChildren().putAll(newEntries);\ntx.commit();\n\n// after\nHibernate.initialize(parent.getChildren());\nparent.getChildren().clear();\nparent.getChildren().putAll(newEntries);","handlingStrategy":"validation","validationCode":"Map<String, Item> children = parent.getChildren();\nif (children instanceof org.hibernate.collection.spi.PersistentCollection pc && !pc.wasInitialized()) {\n    org.hibernate.Hibernate.initialize(children);\n}\nchildren.clear();","typeGuard":null,"tryCatchPattern":"try {\n    tx.commit();\n} catch (org.hibernate.HibernateException e) {\n    Throwable c = e;\n    while (c != null) {\n        if (c instanceof UnsupportedOperationException && String.valueOf(c.getMessage()).contains(\"queued clear\")) {\n            throw new IllegalStateException(\"clear() on uninitialized map with orphanRemoval; initialize first\", e);\n        }\n        c = c.getCause();\n    }\n    throw e;\n}","preventionTips":["Initialize keyed collections before clear() when orphanRemoval is on","Replace entries individually instead of clear+putAll on uninitialized maps","Test the map update flow including flush"],"tags":["hibernate","collections","orphan-removal","lazy-initialization","persistent-map","flush"],"backgroundTag":"orphan-removal-queued-clear","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}