doctrine/orm · error · InvalidArgumentException

Invalid cache usage "%s"

Error message

Invalid cache usage "%s"

What it means

The <cache> element in XML mappings configures second-level caching. Its usage attribute is uppercased and resolved against the ClassMetadata::CACHE_USAGE_* constants; the valid values are READ_ONLY, READ_WRITE and NONSTRICT_READ_WRITE. Anything else (after uppercasing) throws InvalidArgumentException.

Source

Thrown at src/Mapping/Driver/XmlDriver.php:880

            $mapping['options'] = $this->parseOptions($fieldMapping->options->children());
        }

        return $mapping;
    }

    /**
     * Parse / Normalize the cache configuration
     *
     * @return mixed[]
     * @phpstan-return array{usage: int|null, region?: string}
     */
    private function cacheToArray(SimpleXMLElement $cacheMapping): array
    {
        $region = isset($cacheMapping['region']) ? (string) $cacheMapping['region'] : null;
        $usage  = isset($cacheMapping['usage']) ? strtoupper((string) $cacheMapping['usage']) : null;

        if ($usage && ! defined('Doctrine\ORM\Mapping\ClassMetadata::CACHE_USAGE_' . $usage)) {
            throw new InvalidArgumentException(sprintf('Invalid cache usage "%s"', $usage));
        }

        if ($usage) {
            $usage = (int) constant('Doctrine\ORM\Mapping\ClassMetadata::CACHE_USAGE_' . $usage);
        }

        return [
            'usage'  => $usage,
            'region' => $region,
        ];
    }

    /**
     * Gathers a list of cascade options found in the given cascade element.
     *
     * @param SimpleXMLElement $cascadeElement The cascade element.
     *
     * @return string[] The list of cascade options.

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Use one of the three valid values: usage="READ_ONLY", usage="NONSTRICT_READ_WRITE" or usage="READ_WRITE".
2. Pick READ_ONLY for entities that never change after loading (safest and fastest), NONSTRICT_READ_WRITE when slight staleness is acceptable.
3. Check the constant list in Doctrine\ORM\Mapping\ClassMetadata (CACHE_USAGE_*) if your ORM version differs.

Example fix

<!-- before -->
<cache usage="READONLY" region="user_region" />

<!-- after -->
<cache usage="READ_ONLY" region="user_region" />

$usage = strtoupper($usage);
if (! defined(ClassMetadata::class . '::CACHE_USAGE_' . $usage)) {
    throw new InvalidArgumentException("Invalid second-level cache usage '{$usage}'");
}

When it happens

Trigger: Writing <cache usage="READONLY" region="my_region" /> (constant CACHE_USAGE_READONLY does not exist) or invented values like usage="ALL" / usage="transactional"; note underscores are required: READ_ONLY not READONLY.

Common situations: Hand-written cache config guessing at constant names; copying cache usage values from other cache libraries (e.g. JPA/Hibernate 'transactional' or Ehcache 'ALL'); typos in case are harmless (strtoupper is applied) but underscore placement is not.

Related errors

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

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