yiisoft/yii2 · error · UnknownClassException

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

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.

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)

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.