yiisoft/yii2 · error · UnknownClassException

Unable to find '$className' in file: $classFile. Namespace…

Error message

Unable to find '$className' in file: $classFile. Namespace missing?

What it means

Yii's autoloader (BaseYii::autoload) maps a fully-qualified class name to '@' + namespace with '/' separators + '.php', resolves it through the alias map, and includes the file. Under YII_DEBUG it then verifies with class_exists/interface_exists/trait_exists (autoload disabled) that the included file really declared the requested type; if not it throws UnknownClassException. In practice the file was found and included, but its namespace or class name does not match the name that triggered autoloading - the 'Namespace missing?' hint in the message is usually right.

Solutions

1. Open the file printed in the exception and make its namespace and class name match the name in the message (PSR-4: namespace = directory path, class basename = class name)
2. Run composer dump-autoload (add -o for production) after moving, renaming, or adding classes
3. Check that Yii::getAlias('@app') and the psr-4 autoload section in composer.json describe the same source tree
4. If the class is genuinely optional, guard usage with class_exists($class) so the autoloader is never invoked for it

Example fix

// before: app/models/User.php
<?php
class User extends \yii\db\ActiveRecord {}
// new \app\models\User(); => Unable to find 'app\models\User' in file: .../models/User.php. Namespace missing?

// after
<?php
namespace app\models;
class User extends \yii\db\ActiveRecord {}

// Resolve the file the way Yii's autoloader would, without triggering autoload
$file = Yii::getAlias('@' . str_replace('\\', '/', $className) . '.php', false);
if ($file === false || !is_file($file)) {
    // not resolvable via Yii aliases; leave it to Composer or fail softly
}

try {
    $object = new $className();
} catch (\yii\base\UnknownClassException $e) {
    // thrown only when YII_DEBUG; the fix is a namespace correction, not a handler
    Yii::error($e->getMessage());
    throw $e;
}

When it happens

Trigger: Using app\models\User while app/models/User.php declares namespace frontend\models or no namespace at all; a file whose class name differs from its basename (src/InvoiceRepository.php containing class Repo); a case mismatch such as class userService in User.php on a case-sensitive filesystem; a stale Composer classmap after files were moved without dump-autoload.

Common situations: Gii-generated files saved with the wrong namespace; copying classes between the basic and advanced application templates; deploying from macOS/Windows to Linux where filename case suddenly matters; the @app alias pointing at a different source tree than composer.json's psr-4 section so Yii and Composer disagree about which file to load.

Related errors

• Failed to instantiate component or class "$reference->id".

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/bcf1d05a3d40e25e. Report an issue: GitHub.

Appendix: source

Thrown at framework/BaseYii.php:300

    {
        if (isset(static::$classMap[$className])) {
            $classFile = static::$classMap[$className];
            if (strncmp($classFile, '@', 1) === 0) {
                $classFile = static::getAlias($classFile);
            }
        } elseif (strpos($className, '\\') !== false) {
            $classFile = static::getAlias('@' . str_replace('\\', '/', $className) . '.php', false);
            if ($classFile === false || !is_file($classFile)) {
                return;
            }
        } else {
            return;
        }

        include $classFile;

        if (YII_DEBUG && !class_exists($className, false) && !interface_exists($className, false) && !trait_exists($className, false)) {
            throw new UnknownClassException("Unable to find '$className' in file: $classFile. Namespace missing?");
        }
    }

    /**
     * Creates a new object using the given configuration.
     *
     * You may view this method as an enhanced version of the `new` operator.
     * The method supports creating an object based on a class name, a configuration array or
     * an anonymous function.
     *
     * Below are some usage examples:
     *
     * ```
     * // create an object using a class name
     * $object = Yii::createObject('yii\db\Connection');
     *
     * // create an object using a configuration array
     * $object = Yii::createObject([

View on GitHub (pinned to 66f00d18a2)