hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized cache declaration

Error message

Unrecognized cache declaration

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/LoadedConfig.java:156

			return new CacheRegionDefinition(
					CacheRegionDefinition.CacheRegionType.ENTITY,
					jaxbClassCache.getClazz(),
					jaxbClassCache.getUsage().value(),
					jaxbClassCache.getRegion(),
					"all".equals( jaxbClassCache.getInclude() )
			);
		}
		else if ( cacheDeclaration instanceof JaxbCfgCollectionCacheType jaxbCollectionCache ) {
			return new CacheRegionDefinition(
					CacheRegionDefinition.CacheRegionType.COLLECTION,
					jaxbCollectionCache.getCollection(),
					jaxbCollectionCache.getUsage().value(),
					jaxbCollectionCache.getRegion(),
					false
			);
		}
		else {
			throw new IllegalArgumentException( "Unrecognized cache declaration" );
		}
	}

	public void addCacheRegionDefinition(CacheRegionDefinition cacheRegionDefinition) {
		if ( cacheRegionDefinitions == null ) {
			cacheRegionDefinitions = new ArrayList<>();
		}
		cacheRegionDefinitions.add( cacheRegionDefinition );
	}

	public void addEventListener(EventType<?> eventType, String listenerClass) {
		if ( eventListenerMap == null ) {
			eventListenerMap = new HashMap<>();
		}

		Set<String> listenerClasses = eventListenerMap.get( eventType );
		if ( listenerClasses == null ) {
			listenerClasses = new HashSet<>();

View on GitHub (pinned to fad1729dce)

Solutions

1. Run mvn dependency:tree (or gradle dependencies) and align every hibernate artifact to one version
2. Remove legacy duplicate jars such as hibernate-entitymanager (merged into hibernate-core since 5.2)
3. Confirm hibernate.cfg.xml only uses the supported <class-cache/> and <collection-cache/> elements with valid usage/region attributes
4. If you maintain a fork, extend the converter to return a CacheRegionDefinition for the new declaration type instead of falling through

Example fix

// before: mixed versions on the classpath
implementation("org.hibernate:hibernate-core:5.4.30.Final")
runtimeOnly("org.hibernate:hibernate-entitymanager:5.2.18.Final")

// after: single aligned version, enforced with dependencyConvergence
implementation("org.hibernate.orm:hibernate-core:6.4.2.Final")

// Detect multiple hibernate-core versions on the classpath before boot
Enumeration<URL> roots = getClass().getClassLoader()
        .getResources("org/hibernate/cfg/Configuration.class");
if (Collections.list(roots).size() > 1) {
    throw new IllegalStateException("Multiple hibernate-core jars on the classpath - align versions");
}

try {
    new Configuration().configure(cfgXml);
}
catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unrecognized cache declaration")) {
        // almost certainly mixed hibernate-core versions: run dependency:tree and align
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Stream error handling schema url [%s]
• <mapping/> named unexpected reference type
• Annotation '@" + annotation.annotationType().getName() + "'
• Unable to perform extended enhancement - No unique field [%s
• Unable to initialize EventType map

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/a0b6b1572b06dffe. Report an issue: GitHub.