{"record":{"id":"552e0886ba64924d","repo":"hibernate/hibernate-orm","slug":"caching-was-not-configured-for-entity-natural-id","errorCode":null,"errorMessage":"Caching was not configured for entity natural id: ","messagePattern":"Caching was not configured for entity natural id: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java","lineNumber":107,"sourceCode":"\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) {\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","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java#L89-L125","documentation":"getNaturalIdDataAccess returns the access object for an entity's natural-id cache. It is registered only when the mapping enables natural-id caching: the entity is @Cache-annotated, carries @NaturalId fields, and natural-id caching is requested via @NaturalIdCache (or the hbm.xml natural-id cache setting). Otherwise no NaturalIdDataAccess exists for the role and the lookup throws IllegalArgumentException.","triggerScenarios":"Calling getNaturalIdDataAccess for an entity lacking @NaturalIdCache; session.bySimpleNaturalId().load() flows assuming natural-id caching defaults to on; programmatic cache eviction/management touching natural-id regions that were never built.","commonSituations":"Adding @NaturalId without @NaturalIdCache and expecting L2 hits on natural-id lookups; refactors that drop the annotation; test SessionFactories built with minimal mappings.","solutions":["Add @org.hibernate.annotations.NaturalIdCache to the entity (and keep @Cache on it plus @NaturalId on the fields)","Confirm entity-level caching is enabled - natural-id caching only works on top of entity caching","Check the role string matches the entity name used in mappings","Use sessionFactory.getCache().evictNaturalId* helpers rather than the raw region API"],"exampleFix":"// before\n@Entity\n@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)\npublic class User { @NaturalId String ssn; } // no natural-id cache registered\n\n// after\n@Entity\n@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)\n@NaturalIdCache\npublic class User { @NaturalId String ssn; }","handlingStrategy":"validation","validationCode":"if (sessionFactory.getDomainModel().getEntityDescriptor(User.class)\n        .getNaturalIdCacheAccessStrategy() == null) {\n    // natural-id caching not enabled; avoid getNaturalIdDataAccess for this entity\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair @NaturalId fields with @NaturalIdCache when lookups must hit the L2 cache","Confirm entity-level @Cache is present - natural-id caching depends on it","Query sessionFactory.getCache() capabilities instead of assuming regions exist"],"tags":["hibernate","second-level-cache","natural-id","configuration"],"backgroundTag":"caching-not-configured","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}