What causes "Not implemented by caching provider" in hibernate/hibernate-orm?

Override createDomainDataStorageAccess in your RegionFactoryTemplate subclass to return your DomainDataStorageAccess implementation

hibernate/hibernate-orm · critical · UnsupportedOperationException

Not implemented by caching provider

Error message

Not implemented by caching provider

What it means

RegionFactoryTemplate is the base class for second-level cache integrations. Its createDomainDataStorageAccess has no default implementation and throws UnsupportedOperationException; every concrete provider must override it to supply the storage object behind a domain data region. Seeing this error means the configured RegionFactory class does not implement the storage creation the template requires, so the SessionFactory cannot build cache regions.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/cache/spi/support/RegionFactoryTemplate.java:46

		return new DomainDataRegionTemplate(
				regionConfig,
				this,
				createDomainDataStorageAccess( regionConfig, buildingContext ),
				getImplicitCacheKeysFactory(),
				buildingContext
		);
	}

	@Nonnull
	protected CacheKeysFactory getImplicitCacheKeysFactory() {
		return DefaultCacheKeysFactory.INSTANCE;
	}

	@Nonnull
	protected DomainDataStorageAccess createDomainDataStorageAccess(
			@Nonnull DomainDataRegionConfig regionConfig,
			@Nonnull DomainDataRegionBuildingContext buildingContext) {
		throw new UnsupportedOperationException( "Not implemented by caching provider" );
	}

	@Override
	@Nonnull
	public QueryResultsRegion buildQueryResultsRegion(
			@Nonnull String regionName,
			@Nonnull SessionFactoryImplementor sessionFactory) {
		verifyStarted();
		return new QueryResultsRegionTemplate(
				regionName,
				this,
				createQueryResultsRegionStorageAccess( regionName, sessionFactory )
		);
	}

	@Nonnull
	protected abstract StorageAccess createQueryResultsRegionStorageAccess(
			@Nonnull String regionName,

View on GitHub (pinned to fad1729dce)

Solutions

Override createDomainDataStorageAccess in your RegionFactoryTemplate subclass to return your DomainDataStorageAccess implementation
Switch to a maintained provider factory (hibernate-jcache with Caffeine/Ehcache, Infinispan) instead of a custom one
Check the hibernate.cache.region.factory_class value for typos and version match with your Hibernate version
Put @Override on every template method you implement so signature drift becomes a compile error

Example fix

// before
public class MyRegionFactory extends RegionFactoryTemplate {
    // createDomainDataStorageAccess not overridden -> "Not implemented by caching provider"
}

// after
public class MyRegionFactory extends RegionFactoryTemplate {
    @Override
    protected DomainDataStorageAccess createDomainDataStorageAccess(
            DomainDataRegionConfig regionConfig,
            DomainDataRegionBuildingContext context) {
        return new MyDomainDataStorageAccess(createRegion(regionConfig.getStorageAccessType(), regionConfig));
    }
}

Defensive patterns

Strategy: validation

Validate before calling

// fail fast at config load time
Class<?> factoryClass = Class.forName(factoryClassName);
if (Modifier.isAbstract(factoryClass.getModifiers())
        || !RegionFactoryTemplate.class.isAssignableFrom(factoryClass)) {
    throw new IllegalStateException("Invalid hibernate.cache.region.factory_class: "
            + factoryClassName);
}

Try / catch

try {
    sessionFactory = configuration.buildSessionFactory(serviceRegistry);
} catch (UnsupportedOperationException e) {
    if ("Not implemented by caching provider".equals(e.getMessage())) {
        throw new IllegalStateException(
                "RegionFactory '" + factoryClassName + "' is incomplete for this Hibernate version;"
                        + " use a maintained provider or implement createDomainDataStorageAccess", e);
    }
    throw e;
}

Prevention

Run a CI smoke test that builds the SessionFactory with production cache configuration
Pin cache provider versions matched to the Hibernate version
Use maintained providers (hibernate-jcache, Infinispan) unless you can maintain a custom RegionFactory

When it happens

Trigger: A custom RegionFactory extends RegionFactoryTemplate without overriding createDomainDataStorageAccess; hibernate.cache.region.factory_class points at the template itself or an outdated provider built against an older Hibernate API; a Hibernate upgrade changed the template method signature so an existing override no longer overrides anything.

Common situations: Writing an in-house cache integration; upgrading Hibernate major versions while a third-party region factory lags behind; wrong or misspelled factory class name in configuration.

Related errors

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