yiisoft/yii2 · error · InvalidConfigException

The "basePath" property must be set.

Error message

The "basePath" property must be set.

What it means

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.

Source

Thrown at framework/base/Theme.php:141

     */
    public function setBasePath($path)
    {
        $this->_basePath = Yii::getAlias($path);
    }

    /**
     * Converts a file to a themed file if possible.
     * If there is no corresponding themed file, the original file will be returned.
     * @param string $path the file to be themed
     * @return string the themed file, or the original file if the themed version is not available.
     * @throws InvalidConfigException if [[basePath]] is not set
     */
    public function applyTo($path)
    {
        $pathMap = $this->pathMap;
        if (empty($pathMap)) {
            if (($basePath = $this->getBasePath()) === null) {
                throw new InvalidConfigException('The "basePath" property must be set.');
            }
            $pathMap = [Yii::$app->getBasePath() => [$basePath]];
        }
        $path = FileHelper::normalizePath($path);
        foreach ($pathMap as $from => $tos) {
            $from = FileHelper::normalizePath(Yii::getAlias($from)) . DIRECTORY_SEPARATOR;
            if (strpos($path, $from) === 0) {
                $n = strlen($from);
                foreach ((array) $tos as $to) {
                    $to = FileHelper::normalizePath(Yii::getAlias($to)) . DIRECTORY_SEPARATOR;
                    $file = $to . substr($path, $n);
                    if (is_file($file)) {
                        return $file;
                    }
                }
            }
        }

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Set pathMap (preferred when you only want to remap specific directories): 'pathMap' => ['@app/views' => '@app/themes/basic/views'].
2. Or set basePath to the theme view directory: 'basePath' => '@app/themes/basic'.
3. Verify the property name spelling and that the theme array actually reaches the view component (dump Yii::$app->view->theme).
4. If theming is not needed, remove the 'theme' key entirely instead of leaving an empty component.

Example fix

// before
'components' => [
    'view' => [
        'theme' => ['baseUrl' => '@web/themes/basic'], // no pathMap/basePath -> applyTo() throws
    ],
],

// after
'components' => [
    'view' => [
        'theme' => [
            'pathMap' => ['@app/views' => '@app/themes/basic/views'],
            'baseUrl' => '@web/themes/basic',
        ],
    ],
],

// Before enabling/using a theme for view rendering
$theme = Yii::$app->view->theme;
if ($theme !== null && empty($theme->pathMap) && $theme->getBasePath() === null) {
    throw new \yii\base\InvalidConfigException('Theme needs pathMap or basePath before rendering views.');
    // or: Yii::$app->view->theme = null; to disable theming instead of failing
}

When it happens

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

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

Related errors

• The "baseUrl" property must be set.
• Unable to locate view file for view '$view': no active contr
• Unable to resolve view file for view '$view': no active view
• The view file does not exist: $viewFile
• Expecting end() of {widget}, found {calledClass}

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