{"record":{"id":"c9ff5d419dcb44c8","repo":"yiisoft/yii2","slug":"the-basepath-property-must-be-set","errorCode":null,"errorMessage":"The \"basePath\" property must be set.","messagePattern":"The \"basePath\" property must be set\\.","errorType":"exception","errorClass":"InvalidConfigException","httpStatus":null,"severity":"error","filePath":"framework/base/Theme.php","lineNumber":141,"sourceCode":"     */\n    public function setBasePath($path)\n    {\n        $this->_basePath = Yii::getAlias($path);\n    }\n\n    /**\n     * Converts a file to a themed file if possible.\n     * If there is no corresponding themed file, the original file will be returned.\n     * @param string $path the file to be themed\n     * @return string the themed file, or the original file if the themed version is not available.\n     * @throws InvalidConfigException if [[basePath]] is not set\n     */\n    public function applyTo($path)\n    {\n        $pathMap = $this->pathMap;\n        if (empty($pathMap)) {\n            if (($basePath = $this->getBasePath()) === null) {\n                throw new InvalidConfigException('The \"basePath\" property must be set.');\n            }\n            $pathMap = [Yii::$app->getBasePath() => [$basePath]];\n        }\n        $path = FileHelper::normalizePath($path);\n        foreach ($pathMap as $from => $tos) {\n            $from = FileHelper::normalizePath(Yii::getAlias($from)) . DIRECTORY_SEPARATOR;\n            if (strpos($path, $from) === 0) {\n                $n = strlen($from);\n                foreach ((array) $tos as $to) {\n                    $to = FileHelper::normalizePath(Yii::getAlias($to)) . DIRECTORY_SEPARATOR;\n                    $file = $to . substr($path, $n);\n                    if (is_file($file)) {\n                        return $file;\n                    }\n                }\n            }\n        }\n","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/base/Theme.php#L123-L159","documentation":"Thrown by yii\\base\\Theme::applyTo() when it must map a view file to its themed counterpart but cannot: pathMap is empty and basePath is null. With no pathMap, applyTo() falls back to a default mapping of the application base path onto the theme basePath, so at least one of the two properties must be set. View::renderFile() calls applyTo() on every render when a theme is active, so any view rendering can surface this.","triggerScenarios":"Configuring 'view' => ['theme' => []] or a theme with only baseUrl set, then rendering any view; a typo like 'pathmap' => ... leaving the real property null; instantiating Theme directly and passing it to the view component without properties; enabling a theme in config that never receives its definition (config file not loaded).","commonSituations":"Adding a theme only to rewrite asset URLs (baseUrl) and forgetting that view rendering also routes through applyTo(); copy-pasted theme config from a tutorial that omitted pathMap/basePath; theme config placed in web.php while console/queue workers share the rendering code; refactor renaming the theme class so the config array no longer applies.","solutions":["Set pathMap (preferred when you only want to remap specific directories): 'pathMap' => ['@app/views' => '@app/themes/basic/views'].","Or set basePath to the theme view directory: 'basePath' => '@app/themes/basic'.","Verify the property name spelling and that the theme array actually reaches the view component (dump Yii::$app->view->theme).","If theming is not needed, remove the 'theme' key entirely instead of leaving an empty component."],"exampleFix":"// before\n'components' => [\n    'view' => [\n        'theme' => ['baseUrl' => '@web/themes/basic'], // no pathMap/basePath -> applyTo() throws\n    ],\n],\n\n// after\n'components' => [\n    'view' => [\n        'theme' => [\n            'pathMap' => ['@app/views' => '@app/themes/basic/views'],\n            'baseUrl' => '@web/themes/basic',\n        ],\n    ],\n],","handlingStrategy":"validation","validationCode":"// Before enabling/using a theme for view rendering\n$theme = Yii::$app->view->theme;\nif ($theme !== null && empty($theme->pathMap) && $theme->getBasePath() === null) {\n    throw new \\yii\\base\\InvalidConfigException('Theme needs pathMap or basePath before rendering views.');\n    // or: Yii::$app->view->theme = null; to disable theming instead of failing\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set pathMap (or basePath) in the same config block where the theme component is enabled","Cover theme rendering with a smoke test that renders one view per application (web + console)","Prefer pathMap for partial theming; it never depends on the app base path fallback"],"tags":["php","yii2","theming","views","configuration","rendering"],"backgroundTag":"missing-required-config","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}