{"record":{"id":"1da6d576e8edd78b","repo":"hibernate/hibernate-orm","slug":"caching-was-not-configured-for-entity","errorCode":null,"errorMessage":"Caching was not configured for entity: ","messagePattern":"Caching was not configured for entity: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java","lineNumber":96,"sourceCode":"\n\t}\n\n\t@Nonnull\n\tpublic SessionFactoryImplementor getSessionFactory() {\n\t\treturn sessionFactory;\n\t}\n\n\t@Nonnull\n\tpublic CacheKeysFactory getEffectiveKeysFactory() {\n\t\treturn effectiveKeysFactory;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic EntityDataAccess getEntityDataAccess(@Nonnull NavigableRole rootEntityRole) {\n\t\tfinal var access = entityDataAccessMap.get( rootEntityRole );\n\t\tif ( access == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Caching was not configured for entity: \" + rootEntityRole.getFullPath() );\n\t\t}\n\t\treturn access;\n\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) {","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java#L78-L114","documentation":"AbstractDomainDataRegion.getEntityDataAccess returns the EntityDataAccess registered for an entity role when the region was built from caching mappings. If the entity has no cache mapping (@org.hibernate.annotations.Cache / <cache usage=.../>), nothing is registered under its NavigableRole and the lookup throws IllegalArgumentException. The request asked a region for entity data caching that was never configured for that entity.","triggerScenarios":"Calling region.getEntityDataAccess(role) or persister cache-access paths for an entity without @Cache; programmatic metadata that skips cache enabling; using a region or role string belonging to a different SessionFactory; enabling only natural-id or collection caching and then requesting entity data access.","commonSituations":"Assuming shared-cache-mode ENABLE_SELECTIVE or a global default caches every entity; custom cache-management code and tests touching regions while mappings lack @Cache; wrong role strings after entity renames.","solutions":["Annotate the entity with @org.hibernate.annotations.Cache(usage = ...) or add <cache usage=\"...\"/> to its mapping","Verify persistence.xml shared-cache-mode and hibernate.cache.default_cache_concurrency_strategy actually enable entity caching","Check that the NavigableRole string you pass equals the entity name used in mappings","Use sessionFactory.getCache() helpers and persister.hasCache() instead of the internal DomainDataRegion API"],"exampleFix":"// before\n@Entity\npublic class Country { ... } // no @Cache -> getEntityDataAccess(role) throws\n\n// after\n@Entity\n@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_ONLY)\npublic class Country { ... }","handlingStrategy":"validation","validationCode":"EntityPersister persister = sessionFactory.getDomainModel()\n        .getEntityDescriptor(Country.class);\nif (!persister.hasCache()) {\n    // entity caching not configured; skip custom cache handling for this entity\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check persister.hasCache() before touching EntityDataAccess","Keep a startup assertion that every entity used by cache utilities carries @Cache","Prefer sessionFactory.getCache() helpers over raw DomainDataRegion lookups"],"tags":["hibernate","second-level-cache","configuration","entity"],"backgroundTag":"caching-not-configured","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}