{"record":{"id":"b09fb5e3c1d56e14","repo":"yiisoft/yii2","slug":"invalid-path-alias-alias","errorCode":null,"errorMessage":"Invalid path alias: $alias","messagePattern":"Invalid path alias: \\$alias","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"framework/BaseYii.php","lineNumber":158,"sourceCode":"        }\n\n        $pos = strpos($alias, '/');\n        $root = $pos === false ? $alias : substr($alias, 0, $pos);\n\n        if (isset(static::$aliases[$root])) {\n            if (is_string(static::$aliases[$root])) {\n                return $pos === false ? static::$aliases[$root] : static::$aliases[$root] . substr($alias, $pos);\n            }\n\n            foreach (static::$aliases[$root] as $name => $path) {\n                if (strpos($alias . '/', $name . '/') === 0) {\n                    return $path . substr($alias, strlen($name));\n                }\n            }\n        }\n\n        if ($throwException) {\n            throw new InvalidArgumentException(\"Invalid path alias: $alias\");\n        }\n\n        return false;\n    }\n\n    /**\n     * Returns the root alias part of a given alias.\n     * A root alias is an alias that has been registered via [[setAlias()]] previously.\n     * If a given alias matches multiple root aliases, the longest one will be returned.\n     * @param string $alias the alias\n     * @return string|false the root alias, or false if no root alias is found\n     */\n    public static function getRootAlias($alias)\n    {\n        $pos = strpos($alias, '/');\n        $root = $pos === false ? $alias : substr($alias, 0, $pos);\n\n        if (isset(static::$aliases[$root])) {","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/BaseYii.php#L140-L176","documentation":"Yii resolves '@'-prefixed paths exclusively through the static alias map maintained by Yii::setAlias() (built-in roots like @app, @runtime, @vendor plus user-defined ones). Yii::getAlias() throws InvalidArgumentException('Invalid path alias: ...') when the root segment of the alias - e.g. '@foo' in '@foo/bar/file.php' - is not present in Yii::$aliases, because there is no filesystem fallback. Almost every config option documented to accept a path alias (runtimePath, log file targets, component path options) funnels through this method, so the throw can surface far from the call site.","triggerScenarios":"Calling Yii::getAlias('@uploads/invoices/1.png') without Yii::setAlias('@uploads', ...) beforehand; putting an alias into config such as 'runtimePath' => '@backups/logs' or a log target 'logFile' => '@logs/app.log' whose root was never registered; the Yii autoloader resolving a class name to '@app/models/User.php' when '@app' is not set (bare autoload without a fully booted app).","commonSituations":"Typo in an alias written in a config file ('@vendr', '@ap/runtime'); using web-only aliases like @web or @webroot in a console application where only the web entry script defines them; installing an extension whose README uses '@foo' without shipping the required setAlias() step; alias registered in web/index.php but the equivalent bootstrap missing from the console entry script.","solutions":["var_dump(Yii::$aliases) and compare the registered roots with the alias in the message - a typo is the most common cause","Register the alias in the application config under the 'aliases' key (Application::preInit applies it): 'aliases' => ['@uploads' => '@app/uploads']","Or call Yii::setAlias('@uploads', dirname(__DIR__) . '/uploads') in the entry script before anything uses the alias","For console apps that need web aliases, set them explicitly (Yii::setAlias('@webroot', dirname(__DIR__) . '/web')) since only the web entry script defines them"],"exampleFix":"// before\n$path = Yii::getAlias('@uploads/invoices/17.pdf');\n// InvalidArgumentException: Invalid path alias: @uploads/invoices/17.pdf\n\n// after (config/web.php)\nreturn [\n    'id' => 'myapp',\n    'aliases' => [\n        '@uploads' => '@app/uploads',\n    ],\n];","handlingStrategy":"validation","validationCode":"// getAlias() has a built-in non-throwing mode: pass $throwException = false\n$path = Yii::getAlias($alias, false);\nif ($path === false) {\n    // root alias not registered: register it or take another path\n    Yii::setAlias('@uploads', '@app/uploads');\n    $path = Yii::getAlias($alias);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $path = Yii::getAlias($alias);\n} catch (\\InvalidArgumentException $e) {\n    // message starts with 'Invalid path alias:'\n    Yii::warning($e->getMessage(), __METHOD__);\n    $path = $fallbackPath;\n}","preventionTips":["Centralize every setAlias() call in the app config 'aliases' key instead of scattering them","Never assume @web/@webroot exist in console commands; assert them in the console entry script","Prefer the built-in aliases @app, @runtime, @vendor, @webroot unless a custom one is really required"],"tags":["path-alias","configuration","yii-core","filesystem"],"backgroundTag":"unregistered-path-alias","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}