{"record":{"id":"a0b6b1572b06dffe","repo":"hibernate/hibernate-orm","slug":"unrecognized-cache-declaration","errorCode":null,"errorMessage":"Unrecognized cache declaration","messagePattern":"Unrecognized cache declaration","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/LoadedConfig.java","lineNumber":156,"sourceCode":"\t\t\treturn new CacheRegionDefinition(\n\t\t\t\t\tCacheRegionDefinition.CacheRegionType.ENTITY,\n\t\t\t\t\tjaxbClassCache.getClazz(),\n\t\t\t\t\tjaxbClassCache.getUsage().value(),\n\t\t\t\t\tjaxbClassCache.getRegion(),\n\t\t\t\t\t\"all\".equals( jaxbClassCache.getInclude() )\n\t\t\t);\n\t\t}\n\t\telse if ( cacheDeclaration instanceof JaxbCfgCollectionCacheType jaxbCollectionCache ) {\n\t\t\treturn new CacheRegionDefinition(\n\t\t\t\t\tCacheRegionDefinition.CacheRegionType.COLLECTION,\n\t\t\t\t\tjaxbCollectionCache.getCollection(),\n\t\t\t\t\tjaxbCollectionCache.getUsage().value(),\n\t\t\t\t\tjaxbCollectionCache.getRegion(),\n\t\t\t\t\tfalse\n\t\t\t);\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException( \"Unrecognized cache declaration\" );\n\t\t}\n\t}\n\n\tpublic void addCacheRegionDefinition(CacheRegionDefinition cacheRegionDefinition) {\n\t\tif ( cacheRegionDefinitions == null ) {\n\t\t\tcacheRegionDefinitions = new ArrayList<>();\n\t\t}\n\t\tcacheRegionDefinitions.add( cacheRegionDefinition );\n\t}\n\n\tpublic void addEventListener(EventType<?> eventType, String listenerClass) {\n\t\tif ( eventListenerMap == null ) {\n\t\t\teventListenerMap = new HashMap<>();\n\t\t}\n\n\t\tSet<String> listenerClasses = eventListenerMap.get( eventType );\n\t\tif ( listenerClasses == null ) {\n\t\t\tlistenerClasses = new HashSet<>();","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/LoadedConfig.java#L138-L174","documentation":"While converting a parsed hibernate.cfg.xml into a LoadedConfig, Hibernate maps each cache declaration element to a CacheRegionDefinition. It recognizes exactly two JAXB types, JaxbCfgCacheType (entity/class cache) and JaxbCfgCollectionCacheType (collection cache); any other object reaching the else branch throws IllegalArgumentException 'Unrecognized cache declaration'. In practice this only occurs when the JAXB model and the config classes come from different Hibernate versions or a custom extension, because valid cfg.xml can only produce the two known types.","triggerScenarios":"The instanceof chain in LoadedConfig.java matches neither cache declaration type: typically a hibernate-core jar mix on the classpath supplies a JaxbCfg cache type from one version while LoadedConfig comes from another, or a fork added a new cache declaration type without extending this converter.","commonSituations":"Two different hibernate-core (or legacy hibernate-entitymanager) jars on the classpath after a partial upgrade; transitive dependency conflicts in Maven/Gradle; custom Hibernate forks that add new cache declaration variants.","solutions":["Run mvn dependency:tree (or gradle dependencies) and align every hibernate artifact to one version","Remove legacy duplicate jars such as hibernate-entitymanager (merged into hibernate-core since 5.2)","Confirm hibernate.cfg.xml only uses the supported <class-cache/> and <collection-cache/> elements with valid usage/region attributes","If you maintain a fork, extend the converter to return a CacheRegionDefinition for the new declaration type instead of falling through"],"exampleFix":"// before: mixed versions on the classpath\nimplementation(\"org.hibernate:hibernate-core:5.4.30.Final\")\nruntimeOnly(\"org.hibernate:hibernate-entitymanager:5.2.18.Final\")\n\n// after: single aligned version, enforced with dependencyConvergence\nimplementation(\"org.hibernate.orm:hibernate-core:6.4.2.Final\")","handlingStrategy":"validation","validationCode":"// Detect multiple hibernate-core versions on the classpath before boot\nEnumeration<URL> roots = getClass().getClassLoader()\n        .getResources(\"org/hibernate/cfg/Configuration.class\");\nif (Collections.list(roots).size() > 1) {\n    throw new IllegalStateException(\"Multiple hibernate-core jars on the classpath - align versions\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    new Configuration().configure(cfgXml);\n}\ncatch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unrecognized cache declaration\")) {\n        // almost certainly mixed hibernate-core versions: run dependency:tree and align\n    }\n    throw e;\n}","preventionTips":["Pin one hibernate version via dependencyManagement / BOM","Enable maven-enforcer (dependencyConvergence, banDuplicatePomDependencyVersions) or Gradle strict version conflicts"],"tags":["hibernate","cfg-xml","cache","version-conflict"],"backgroundTag":"dependency-version-conflict","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}