{"record":{"id":"a655c76bf8ea65d6","repo":"hibernate/hibernate-orm","slug":"caching-was-not-configured-for-collection","errorCode":null,"errorMessage":"Caching was not configured for collection: ","messagePattern":"Caching was not configured for collection: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java","lineNumber":117,"sourceCode":"\t}\n\n\n\t@Override\n\t@Nonnull\n\tpublic NaturalIdDataAccess getNaturalIdDataAccess(@Nonnull NavigableRole rootEntityRole) {\n\t\tfinal var access = naturalIdDataAccessMap.get( rootEntityRole );\n\t\tif ( access == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Caching was not configured for entity natural id: \" + rootEntityRole.getFullPath() );\n\t\t}\n\t\treturn access;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic CollectionDataAccess getCollectionDataAccess(@Nonnull NavigableRole collectionRole) {\n\t\tfinal var access = collectionDataAccessMap.get( collectionRole );\n\t\tif ( access == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Caching was not configured for collection: \" + collectionRole.getFullPath() );\n\t\t}\n\t\treturn access;\n\t}\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// creation\n\n\t@Nonnull\n\tprotected abstract EntityDataAccess generateEntityAccess(@Nonnull EntityDataCachingConfig entityAccessConfig);\n\t@Nonnull\n\tprotected abstract CollectionDataAccess generateCollectionAccess(@Nonnull CollectionDataCachingConfig cachingConfig);\n\t@Nonnull\n\tprotected abstract NaturalIdDataAccess generateNaturalIdAccess(@Nonnull NaturalIdDataCachingConfig naturalIdAccessConfig);\n\n\tprivate Map<NavigableRole, EntityDataAccess> generateEntityDataAccessMap(\n\t\t\t@Nonnull DomainDataRegionConfig regionConfig) {\n\t\tfinal var entityCaching = regionConfig.getEntityCaching();\n\t\tif ( entityCaching.isEmpty() ) {","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java#L99-L135","documentation":"getCollectionDataAccess returns the access strategy for a collection role. A CollectionDataAccess is registered only when the collection mapping itself carries cache settings (@Cache on the @OneToMany/@ManyToMany property or <collection-cache/> in hbm.xml). Requesting a collection role without that mapping throws IllegalArgumentException. Caching the owner entity does not cache its collections.","triggerScenarios":"Calling getCollectionDataAccess for a @OneToMany mapped without @Cache; expecting collection caching because the owner entity is @Cache-annotated; passing a role string like 'Entity.children' that does not exactly match the mapped role.","commonSituations":"Forgetting the collection-level @Cache annotation; shared-cache-mode setups where collection caching is assumed; typos in role strings inside custom cache tooling.","solutions":["Add @org.hibernate.annotations.Cache(usage = ...) directly on the collection mapping (or <collection-cache collection=\"...\"/> in hbm.xml)","Verify the role string equals '<OwnerEntityName>.<propertyName>'","Use sessionFactory.getCache() evictCollection* helpers instead of the raw region API","Confirm the collection side, not just the entity side, has cache configuration"],"exampleFix":"// before\n@OneToMany(mappedBy = \"order\", fetch = FetchType.LAZY)\nList<OrderLine> lines; // collection not cached\n\n// after\n@OneToMany(mappedBy = \"order\", fetch = FetchType.LAZY)\n@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)\nList<OrderLine> lines;","handlingStrategy":"validation","validationCode":"CollectionPersister cp = sessionFactory.getDomainModel()\n        .findCollectionDescriptor(Order.class.getName() + \".lines\");\nif (cp == null || !cp.hasCache()) {\n    // collection caching not configured; skip cache handling\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add @Cache on the collection mapping whenever the collection is cache-managed","Verify role strings '<Entity>.<property>' when using region APIs","Use sessionFactory.getCache().evictCollection* helpers rather than raw regions"],"tags":["hibernate","second-level-cache","collection","configuration"],"backgroundTag":"caching-not-configured","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}