doctrine/orm · error · InvalidArgumentException

Unrecognized access strategy type [%s]

Error message

Unrecognized access strategy type [%s]

What it means

InvalidArgumentException from DefaultCacheFactory::buildCachedEntityPersister() (src/Cache/DefaultCacheFactory.php:88). The `usage` value in the entity's cache metadata is none of the recognized integers (ClassMetadata::CACHE_USAGE_READ_ONLY=1, CACHE_USAGE_NONSTRICT_READ_WRITE=2, CACHE_USAGE_READ_WRITE=3). The factory cannot pick a persister strategy for an unknown value.

Source

Thrown at src/Cache/DefaultCacheFactory.php:88

        $usage  = $metadata->cache['usage'];

        if ($usage === ClassMetadata::CACHE_USAGE_READ_ONLY) {
            return new ReadOnlyCachedEntityPersister($persister, $region, $em, $metadata);
        }

        if ($usage === ClassMetadata::CACHE_USAGE_NONSTRICT_READ_WRITE) {
            return new NonStrictReadWriteCachedEntityPersister($persister, $region, $em, $metadata);
        }

        if ($usage === ClassMetadata::CACHE_USAGE_READ_WRITE) {
            if (! $region instanceof ConcurrentRegion) {
                throw new InvalidArgumentException(sprintf('Unable to use access strategy type of [%s] without a ConcurrentRegion', $usage));
            }

            return new ReadWriteCachedEntityPersister($persister, $region, $em, $metadata);
        }

        throw new InvalidArgumentException(sprintf('Unrecognized access strategy type [%s]', $usage));
    }

    public function buildCachedCollectionPersister(
        EntityManagerInterface $em,
        CollectionPersister $persister,
        AssociationMapping $mapping,
    ): CachedCollectionPersister {
        assert(isset($mapping->cache));
        $usage  = $mapping->cache['usage'];
        $region = $this->getRegion($mapping->cache);

        if ($usage === ClassMetadata::CACHE_USAGE_READ_ONLY) {
            return new ReadOnlyCachedCollectionPersister($persister, $region, $em, $mapping);
        }

        if ($usage === ClassMetadata::CACHE_USAGE_NONSTRICT_READ_WRITE) {
            return new NonStrictReadWriteCachedCollectionPersister($persister, $region, $em, $mapping);
        }

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Clear the metadata cache (the query/metadata cache pool) so mappings are rebuilt with the installed ORM version.
2. In custom drivers/code, always set usage from ClassMetadata constants: $metadata->enableCache(usage: ClassMetadata::CACHE_USAGE_READ_ONLY).
3. Validate mapping files: usage must be READ_ONLY, NONSTRICT_READ_WRITE, or READ_WRITE (drivers convert these names to the constants).
4. Dump $metadata->cache for the offending class to find which value slips through and where it originates.

Example fix

// before (custom driver writing a raw value)
$metadata->cache = ['usage' => 0, 'region' => 'default']; // 0 is not a valid usage

// after
use Doctrine\ORM\Mapping\ClassMetadata;
$metadata->enableCache(usage: ClassMetadata::CACHE_USAGE_READ_ONLY, region: 'default');

// When building metadata programmatically, validate the usage constant
$usage = $metadata->cache['usage'] ?? null;
assert(in_array($usage, [
    ClassMetadata::CACHE_USAGE_READ_ONLY,
    ClassMetadata::CACHE_USAGE_NONSTRICT_READ_WRITE,
    ClassMetadata::CACHE_USAGE_READ_WRITE,
], true));

When it happens

Trigger: Programmatically built or serialized ClassMetadata whose cache['usage'] holds an invalid value: metadata produced by a custom mapping driver, metadata loaded from a stale metadata cache written by an older/other ORM version, or code assigning a string/int literal instead of the ClassMetadata constants.

Common situations: Deploying an ORM upgrade without clearing the metadata cache (old serialized ClassMetadata definitions); home-grown annotation/XML drivers that bypass the built-in constant resolution; importing mappings from another project with a custom usage enum.

Related errors

• Unable to use access strategy type of [%s] without a Concurr
• If you want to use a "READ_WRITE" cache an implementation of
• The directory "%s" does not exist and could not be created.
• The directory "%s" is not writable.
• Unknown property {key} on class {class}

AI-assisted analysis of doctrine/orm@d9b9ff7301 (2026-08-21). Data as JSON: /api/errors/37fb60525aafb66f. Report an issue: GitHub.