cakephp/cakephp · error · NotFoundException

Alias ( ) is not an existing class and therefore cannot be…

Error message

Alias (%s) is not an existing class and therefore cannot be resolved

What it means

ReflectionContainer::get() resolves services by instantiating the class named by $id using reflection. Before doing so it checks $this->has($id), which requires $id to be an existing class (or interface with implementations resolvable); otherwise it throws NotFoundException because a non-class alias cannot be reflected. Unlike the full Container, reflection resolution only works for real class names.

Solutions

1. Pass the fully-qualified class name instead of a service alias, or register the alias in the main container and resolve through it
2. Attach the ReflectionContainer as a delegate ($container->delegate($reflection)) so aliases resolve via definitions first
3. Fix autoloading: run composer dump-autoload and verify class_exists($id) is true
4. Check the namespace/casing of the class name

Example fix

// before
$db = $reflectionContainer->get('db'); // alias, not a class
// after
$db = $container->get('db'); // main container, or:
$db = $reflectionContainer->get(App\Db::class);

if (!class_exists($id) && !interface_exists($id)) {
    throw new LogicException("ReflectionContainer requires a real class; '$id' is not autoloadable");
}

function isReflectionResolvable(string $id): bool {
    return class_exists($id) || interface_exists($id);
}

try {
    $obj = $reflectionContainer->get($id);
} catch (NotFoundException $e) {
    $obj = $container->has($id) ? $container->get($id) : null;
}

When it happens

Trigger: $reflectionContainer->get('service.alias') where the alias is a string id, not a FQCN; calling get() with a class name that was never autoloaded (missing require/include, composer dump-autoload not run); asking for an interface without a registered alias.

Common situations: Using the reflection container standalone (not as a delegate of the main container) with string-based service ids; autoloader misconfiguration after moving a class; typos in namespaces (case-sensitive class names).

Related errors

• Unable to resolve a value for parameter
• Alias ( ) has a non-public constructor and therefore cannot…
• Callable ( ) is not a valid callable
• Incorrect type for value.
• Unable to extend alias

AI-assisted analysis of cakephp/cakephp@1128eba9b0 (2026-09-12). Data as JSON: /api/errors/16da722a3444e5bd. Report an issue: GitHub.

Appendix: source

Thrown at src/Container/ReflectionContainer.php:49

     * @param bool $cacheResolutions
     */
    public function __construct(bool $cacheResolutions = false)
    {
        $this->cacheResolutions = $cacheResolutions;
    }

    /**
     * @inheritDoc
     */
    public function get(string $id, array $args = [])
    {
        // Only use cache when no custom args are provided
        if ($this->cacheResolutions && $args === [] && array_key_exists($id, $this->cache)) {
            return $this->cache[$id];
        }

        if (!$this->has($id)) {
            throw new NotFoundException(
                sprintf('Alias (%s) is not an existing class and therefore cannot be resolved', $id),
            );
        }

        /** @var class-string $id */
        $reflector = new ReflectionClass($id);
        $construct = $reflector->getConstructor();

        if ($construct && !$construct->isPublic()) {
            throw new NotFoundException(
                sprintf('Alias (%s) has a non-public constructor and therefore cannot be instantiated', $id),
            );
        }

        $resolution = $construct === null
            ? new $id()
            : $reflector->newInstanceArgs($this->reflectArguments($construct, $args));

View on GitHub (pinned to 1128eba9b0)