{"record":{"id":"36c1ab0b54b545fc","repo":"yiisoft/yii2","slug":"the-directory-does-not-exist-path","errorCode":null,"errorMessage":"The directory does not exist: $path","messagePattern":"The directory does not exist: \\$path","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"critical","filePath":"framework/base/Module.php","lineNumber":258,"sourceCode":"        }\n\n        return $this->_basePath;\n    }\n\n    /**\n     * Sets the root directory of the module.\n     * This method can only be invoked at the beginning of the constructor.\n     * @param string $path the root directory of the module. This can be either a directory name or a [path alias](guide:concept-aliases).\n     * @throws InvalidArgumentException if the directory does not exist.\n     */\n    public function setBasePath($path)\n    {\n        $path = Yii::getAlias($path);\n        $p = strncmp($path, 'phar://', 7) === 0 ? $path : realpath($path);\n        if (is_string($p) && is_dir($p)) {\n            $this->_basePath = $p;\n        } else {\n            throw new InvalidArgumentException(\"The directory does not exist: $path\");\n        }\n    }\n\n    /**\n     * Returns the directory that contains the controller classes according to [[controllerNamespace]].\n     * Note that in order for this method to return a value, you must define\n     * an alias for the root namespace of [[controllerNamespace]].\n     * @return string the directory that contains the controller classes.\n     * @throws InvalidArgumentException if there is no alias defined for the root namespace of [[controllerNamespace]].\n     */\n    public function getControllerPath()\n    {\n        if ($this->_controllerPath === null) {\n            $this->_controllerPath = Yii::getAlias('@' . str_replace('\\\\', '/', $this->controllerNamespace));\n        }\n\n        return $this->_controllerPath;\n    }","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/base/Module.php#L240-L276","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the resolved value with is_dir(Yii::getAlias($config['basePath'])) using the exact config string","For aliases, ensure Yii::setAlias('@mymodule', ...) runs in the entry script before the module is instantiated, or pass a plain absolute path","Fix the dirname() level in entry scripts/config after relocating files (e.g. dirname(__DIR__, 2))","Verify exact case and existence of each path segment on the target host (ls the resolved path)"],"exampleFix":"// before\nnew \\yii\\web\\Application([\n    'basePath' => '@backend', // alias not registered yet → The directory does not exist: @backend\n]);\n\n// after\nYii::setAlias('@backend', '/var/www/advanced/backend');\nnew \\yii\\web\\Application([\n    'basePath' => '@backend',\n]);","handlingStrategy":"validation","validationCode":"$resolved = Yii::getAlias($config['basePath']);\nif (!is_dir($resolved)) {\n    throw new \\RuntimeException('basePath misconfigured, resolved to: ' . $resolved);\n}","typeGuard":"function isResolvableBasePath(string $path): bool\n{\n    $resolved = Yii::getAlias($path);\n    return strncmp($resolved, 'phar://', 7) === 0 ? true : is_dir($resolved);\n}","tryCatchPattern":"try {\n    new \\yii\\web\\Application($config);\n} catch (\\InvalidArgumentException $e) {\n    // bootstrap-time path failure — log with the deployment context and abort\n}","preventionTips":["Register all path aliases in the entry scripts (web/index.php, console/yii) before the application is created","Run a bootstrap smoke test in CI on a path layout matching production","Prefer @app/@webroot aliases over hand-built dirname() chains"],"tags":["php","yii2","config","bootstrap","path-alias","module"],"backgroundTag":"config-path-not-found","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}