doctrine/orm · error · NotAProxyClass

The class "%s" is not part of the proxy namespace "%s"

Error message

The class "%s" is not part of the proxy namespace "%s"

What it means

Autoloader::resolveFile() maps a proxy class name to a file under the proxy directory by stripping the proxy namespace prefix. The SPL autoloader registered by Autoloader::register() skips any class not starting with the proxy namespace, so this InvalidArgumentException (NotAProxyClass) escapes when resolveFile() is called directly — e.g., by cache warmers, preloading or proxy-generating tooling — with a class outside the configured proxy namespace, or when the proxy namespace in Configuration does not prefix the class being resolved.

Source

Thrown at src/Proxy/Autoloader.php:49

     * 3. Return PHP filename from proxy-dir with the result from 2.
     *
     * @phpstan-param class-string $className
     *
     * @throws NotAProxyClass
     */
    public static function resolveFile(string $proxyDir, string $proxyNamespace, string $className): string
    {
        if (PHP_VERSION_ID >= 80400) {
            Deprecation::trigger(
                'doctrine/orm',
                'https://github.com/doctrine/orm/pull/12005',
                'Class "%s" is deprecated. Use native lazy objects instead.',
                self::class,
            );
        }

        if (! str_starts_with($className, $proxyNamespace)) {
            throw new NotAProxyClass($className, $proxyNamespace);
        }

        // remove proxy namespace from class name
        $classNameRelativeToProxyNamespace = substr($className, strlen($proxyNamespace));

        // remove namespace separators from remaining class name
        $fileName = str_replace('\\', '', $classNameRelativeToProxyNamespace);

        return $proxyDir . DIRECTORY_SEPARATOR . $fileName . '.php';
    }

    /**
     * Registers and returns autoloader callback for the given proxy dir and namespace.
     *
     * @param Closure(string, string, class-string): void|null $notFoundCallback Invoked when the proxy file is not found.
     *
     * @return Closure(string): void
     */

View on GitHub (pinned to d9b9ff7301)

Solutions

1. Guard the call: if (! str_starts_with($className, $proxyNamespace)) skip — resolve only proxy namespaced classes
2. Verify Configuration proxy settings: getProxyDir()/getProxyNamespace() match the proxies you actually generate
3. Regenerate proxies (doctrine orm:generate-proxies / cache:clear) after namespace changes
4. On PHP >= 8.4, switch to native lazy objects; the Autoloader is deprecated (PR 12005)

Example fix

// before
$file = Autoloader::resolveFile($proxyDir, $proxyNamespace, $className); // throws for non-proxy classes

// after
if (str_starts_with($className, $proxyNamespace)) {
    $file = Autoloader::resolveFile($proxyDir, $proxyNamespace, $className);
}

if (str_starts_with($className, $proxyNamespace)) {
    $file = Autoloader::resolveFile($proxyDir, $proxyNamespace, $className);
}

function isProxyClassName(string $className, string $proxyNamespace): bool
{
    return $proxyNamespace !== '' && str_starts_with($className, $proxyNamespace);
}

try { $file = Autoloader::resolveFile($dir, $ns, $class); } catch (NotAProxyClass) { /* not a proxy: fall through to normal class handling */ }

When it happens

Trigger: Calling Autoloader::resolveFile($proxyDir, $proxyNamespace, $className) with an entity FQCN or any class not under the proxy namespace; proxy namespace misconfiguration (default 'Proxies', changed via Configuration::setProxyNamespace) so generated proxies no longer share the prefix; on PHP >= 8.4 the whole autoloader path is deprecated in favor of native lazy objects.

Common situations: Custom console commands / deployment scripts iterating classes and resolving proxy file paths; changing the proxy namespace but keeping stale generated proxy files; tooling calling resolveFile for arbitrary classes during cache warming.

Related errors

• Doctrine ORM does not support property hook on %s::%s withou
• Lazy loading proxies require PHP 8.4 or higher.
• Proxy directory cannot be null
• Proxies destination directory '<info>%s</info>' does not exi
• Proxies destination directory '<info>%s</info>' does not hav

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