yiisoft/yii2 · critical · InvalidArgumentException

The directory does not exist: $path

Error message

The directory does not exist: $path

What it means

yii\base\Module::setBasePath() resolves the configured path via Yii::getAlias() and requires the result to be an existing directory (realpath() for everything except phar:// paths, which are taken as-is). If the directory is missing, realpath() returns false; an undefined alias is returned verbatim with its '@' so it also fails realpath(). The InvalidArgumentException typically fires while the module or application is constructed during bootstrap.

Source

Thrown at framework/base/Module.php:258

        }

        return $this->_basePath;
    }

    /**
     * Sets the root directory of the module.
     * This method can only be invoked at the beginning of the constructor.
     * @param string $path the root directory of the module. This can be either a directory name or a [path alias](guide:concept-aliases).
     * @throws InvalidArgumentException if the directory does not exist.
     */
    public function setBasePath($path)
    {
        $path = Yii::getAlias($path);
        $p = strncmp($path, 'phar://', 7) === 0 ? $path : realpath($path);
        if (is_string($p) && is_dir($p)) {
            $this->_basePath = $p;
        } else {
            throw new InvalidArgumentException("The directory does not exist: $path");
        }
    }

    /**
     * Returns the directory that contains the controller classes according to [[controllerNamespace]].
     * Note that in order for this method to return a value, you must define
     * an alias for the root namespace of [[controllerNamespace]].
     * @return string the directory that contains the controller classes.
     * @throws InvalidArgumentException if there is no alias defined for the root namespace of [[controllerNamespace]].
     */
    public function getControllerPath()
    {
        if ($this->_controllerPath === null) {
            $this->_controllerPath = Yii::getAlias('@' . str_replace('\\', '/', $this->controllerNamespace));
        }

        return $this->_controllerPath;
    }

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Check the resolved value with is_dir(Yii::getAlias($config['basePath'])) using the exact config string
2. For aliases, ensure Yii::setAlias('@mymodule', ...) runs in the entry script before the module is instantiated, or pass a plain absolute path
3. Fix the dirname() level in entry scripts/config after relocating files (e.g. dirname(__DIR__, 2))
4. Verify exact case and existence of each path segment on the target host (ls the resolved path)

Example fix

// before
new \yii\web\Application([
    'basePath' => '@backend', // alias not registered yet → The directory does not exist: @backend
]);

// after
Yii::setAlias('@backend', '/var/www/advanced/backend');
new \yii\web\Application([
    'basePath' => '@backend',
]);

$resolved = Yii::getAlias($config['basePath']);
if (!is_dir($resolved)) {
    throw new \RuntimeException('basePath misconfigured, resolved to: ' . $resolved);
}

function isResolvableBasePath(string $path): bool
{
    $resolved = Yii::getAlias($path);
    return strncmp($resolved, 'phar://', 7) === 0 ? true : is_dir($resolved);
}

try {
    new \yii\web\Application($config);
} catch (\InvalidArgumentException $e) {
    // bootstrap-time path failure — log with the deployment context and abort
}

When it happens

Trigger: Configuring 'basePath' => '@backend' when that alias was never registered (Yii::getAlias returns '@backend' unchanged and realpath fails); dirname(__DIR__) pointing one directory level off after the entry script moved; a case-mismatched path segment on case-sensitive filesystems; a symlink target absent on the deploy host.

Common situations: Advanced-template deployments where frontend/backend aliases differ per host; Docker/Vagrant mounts placing the app at a different absolute path than the config assumes; environment-specific config files with stale absolute paths; moving the project between Windows (case-insensitive) and Linux.

Related errors

• Invalid validation rule: a rule must specify both attribute
• {cipher} is not an allowed cipher
• Failed to generate HMAC with hash algorithm: {macHash}
• Unknown scenario: $scenario
• Controller class must extend from \yii\base\Controller.

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