{"record":{"id":"bcf1d05a3d40e25e","repo":"yiisoft/yii2","slug":"unable-to-find-classname-in-file-classfile-n","errorCode":null,"errorMessage":"Unable to find '$className' in file: $classFile. Namespace missing?","messagePattern":"Unable to find '\\$className' in file: \\$classFile\\. Namespace missing\\?","errorType":"exception","errorClass":"UnknownClassException","httpStatus":null,"severity":"error","filePath":"framework/BaseYii.php","lineNumber":300,"sourceCode":"    {\n        if (isset(static::$classMap[$className])) {\n            $classFile = static::$classMap[$className];\n            if (strncmp($classFile, '@', 1) === 0) {\n                $classFile = static::getAlias($classFile);\n            }\n        } elseif (strpos($className, '\\\\') !== false) {\n            $classFile = static::getAlias('@' . str_replace('\\\\', '/', $className) . '.php', false);\n            if ($classFile === false || !is_file($classFile)) {\n                return;\n            }\n        } else {\n            return;\n        }\n\n        include $classFile;\n\n        if (YII_DEBUG && !class_exists($className, false) && !interface_exists($className, false) && !trait_exists($className, false)) {\n            throw new UnknownClassException(\"Unable to find '$className' in file: $classFile. Namespace missing?\");\n        }\n    }\n\n    /**\n     * Creates a new object using the given configuration.\n     *\n     * You may view this method as an enhanced version of the `new` operator.\n     * The method supports creating an object based on a class name, a configuration array or\n     * an anonymous function.\n     *\n     * Below are some usage examples:\n     *\n     * ```\n     * // create an object using a class name\n     * $object = Yii::createObject('yii\\db\\Connection');\n     *\n     * // create an object using a configuration array\n     * $object = Yii::createObject([","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/BaseYii.php#L282-L318","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Run composer dump-autoload (add -o for production) after moving, renaming, or adding classes","Check that Yii::getAlias('@app') and the psr-4 autoload section in composer.json describe the same source tree","If the class is genuinely optional, guard usage with class_exists($class) so the autoloader is never invoked for it"],"exampleFix":"// before: app/models/User.php\n<?php\nclass User extends \\yii\\db\\ActiveRecord {}\n// new \\app\\models\\User(); => Unable to find 'app\\models\\User' in file: .../models/User.php. Namespace missing?\n\n// after\n<?php\nnamespace app\\models;\nclass User extends \\yii\\db\\ActiveRecord {}","handlingStrategy":"validation","validationCode":"// Resolve the file the way Yii's autoloader would, without triggering autoload\n$file = Yii::getAlias('@' . str_replace('\\\\', '/', $className) . '.php', false);\nif ($file === false || !is_file($file)) {\n    // not resolvable via Yii aliases; leave it to Composer or fail softly\n}","typeGuard":null,"tryCatchPattern":"try {\n    $object = new $className();\n} catch (\\yii\\base\\UnknownClassException $e) {\n    // thrown only when YII_DEBUG; the fix is a namespace correction, not a handler\n    Yii::error($e->getMessage());\n    throw $e;\n}","preventionTips":["Keep every class PSR-4 compliant: one class per file, basename = class name, namespace = directory path","Run composer dump-autoload after any file move or rename; add it to build scripts","Run CI on a case-sensitive filesystem (Linux) to catch filename-case mismatches early"],"tags":["autoloading","namespace","composer","class-not-found"],"backgroundTag":"autoloader-namespace-mismatch","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}