yiisoft/yii2 · error · InvalidArgumentException

Invalid path alias: $alias

Error message

Invalid path alias: $alias

What it means

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.

Source

Thrown at framework/BaseYii.php:158

        }

        $pos = strpos($alias, '/');
        $root = $pos === false ? $alias : substr($alias, 0, $pos);

        if (isset(static::$aliases[$root])) {
            if (is_string(static::$aliases[$root])) {
                return $pos === false ? static::$aliases[$root] : static::$aliases[$root] . substr($alias, $pos);
            }

            foreach (static::$aliases[$root] as $name => $path) {
                if (strpos($alias . '/', $name . '/') === 0) {
                    return $path . substr($alias, strlen($name));
                }
            }
        }

        if ($throwException) {
            throw new InvalidArgumentException("Invalid path alias: $alias");
        }

        return false;
    }

    /**
     * Returns the root alias part of a given alias.
     * A root alias is an alias that has been registered via [[setAlias()]] previously.
     * If a given alias matches multiple root aliases, the longest one will be returned.
     * @param string $alias the alias
     * @return string|false the root alias, or false if no root alias is found
     */
    public static function getRootAlias($alias)
    {
        $pos = strpos($alias, '/');
        $root = $pos === false ? $alias : substr($alias, 0, $pos);

        if (isset(static::$aliases[$root])) {

View on GitHub (pinned to 66f00d18a2)

Solutions

1. var_dump(Yii::$aliases) and compare the registered roots with the alias in the message - a typo is the most common cause
2. Register the alias in the application config under the 'aliases' key (Application::preInit applies it): 'aliases' => ['@uploads' => '@app/uploads']
3. Or call Yii::setAlias('@uploads', dirname(__DIR__) . '/uploads') in the entry script before anything uses the alias
4. For console apps that need web aliases, set them explicitly (Yii::setAlias('@webroot', dirname(__DIR__) . '/web')) since only the web entry script defines them

Example fix

// before
$path = Yii::getAlias('@uploads/invoices/17.pdf');
// InvalidArgumentException: Invalid path alias: @uploads/invoices/17.pdf

// after (config/web.php)
return [
    'id' => 'myapp',
    'aliases' => [
        '@uploads' => '@app/uploads',
    ],
];

// getAlias() has a built-in non-throwing mode: pass $throwException = false
$path = Yii::getAlias($alias, false);
if ($path === false) {
    // root alias not registered: register it or take another path
    Yii::setAlias('@uploads', '@app/uploads');
    $path = Yii::getAlias($alias);
}

try {
    $path = Yii::getAlias($alias);
} catch (\InvalidArgumentException $e) {
    // message starts with 'Invalid path alias:'
    Yii::warning($e->getMessage(), __METHOD__);
    $path = $fallbackPath;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• FileDependency::fileName must be set
• Unsupported configuration type: ' . gettype($type)
• Object configuration must be an array containing a "class" o
• The "id" configuration for the Application is required.
• The "basePath" configuration for the Application is required

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