What causes "Unknown access type [" in hibernate/hibernate-orm?

Use one of the exact external names: read-only, read-write, nonstrict-read-write, transactional

hibernate/hibernate-orm · error · UnknownAccessTypeException

Unknown access type [

Error message

Unknown access type [

What it means

Hibernate resolves the textual name of a second-level cache concurrency strategy by matching it against the AccessType enum: first by external name (read-only, read-write, nonstrict-read-write, transactional), then by enum constant name case-insensitively. If the supplied string matches neither, AccessType.fromExternalName throws UnknownAccessTypeException carrying that name. The string almost always comes from a cache usage setting in an annotation, an hbm.xml mapping, or a configuration property.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/cache/spi/access/AccessType.java:88

	 *
	 * @see #getExternalName()
	 */
	@Nullable
	public static AccessType fromExternalName(@Nullable String externalName) {
		if ( externalName == null ) {
			return null;
		}
		for ( AccessType accessType : AccessType.values() ) {
			if ( accessType.getExternalName().equals( externalName ) ) {
				return accessType;
			}
		}
		// Check to see if making upper-case matches an enum name.
		try {
			return AccessType.valueOf( externalName.toUpperCase( Locale.ROOT ) );
		}
		catch ( IllegalArgumentException e ) {
			throw new UnknownAccessTypeException( externalName );
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Use one of the exact external names: read-only, read-write, nonstrict-read-write, transactional
Prefer the enum in code: @Cache(usage = CacheConcurrencyStrategy.READ_WRITE) or AccessType.READ_WRITE instead of raw strings
Verify the configured cache provider actually supports the chosen strategy (e.g. transactional needs a JTA-capable provider)
Remove the usage attribute entirely to accept the provider default instead of an invalid name

Example fix

// before (hbm.xml)
<cache usage="read_write" region="items"/>

// after
<cache usage="read-write" region="items"/>

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> VALID_STRATEGIES =
        Set.of("read-only", "read-write", "nonstrict-read-write", "transactional");

if (cacheStrategyName != null && !VALID_STRATEGIES.contains(cacheStrategyName)) {
    throw new IllegalArgumentException("Unknown cache access type: " + cacheStrategyName
            + " (expected one of " + VALID_STRATEGIES + ")");
}

Type guard

static boolean isValidAccessTypeName(String name) {
    return Arrays.stream(AccessType.values()).anyMatch(
            t -> t.getExternalName().equals(name) || t.name().equalsIgnoreCase(name));
}

Try / catch

try {
    AccessType type = AccessType.fromExternalName(configuredValue);
} catch (UnknownAccessTypeException e) {
    throw new IllegalStateException(
            "Invalid cache strategy '" + configuredValue + "' in configuration", e);
}

Prevention

Validate cache strategy names at startup before building the SessionFactory
Use AccessType or CacheConcurrencyStrategy enum constants instead of strings in code
Add an integration test that builds the SessionFactory with the production cache configuration

When it happens

Trigger: Calling AccessType.fromExternalName(name) with an unrecognized string; usage="read_write" (underscore) in @org.hibernate.annotations.Cache or <cache usage="read_write"/> in hbm.xml; hibernate.cache.default_cache_concurrency_strategy set to a misspelled value; provider configuration feeding a strategy name into Hibernate at startup.

Common situations: Typos in the cache usage attribute (read_write, nonstrictread_write, 'readwrite'); copying strategy names from another cache library; picking a strategy the configured cache provider does not offer; version upgrades where strategy name validation became stricter.

Related errors

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