yiisoft/yii2 · error · InvalidConfigException

The "baseUrl" property must be set.

Error message

The "baseUrl" property must be set.

What it means

Thrown by yii\base\Theme::getUrl() when the baseUrl property was never set. getUrl() concatenates baseUrl with a relative URL to build absolute theme asset URLs, and unlike some components it has no fallback derivation from basePath, so a null baseUrl is an error. It is a pure configuration guard: the getter returns the raw stored value and the exception fires when it is null.

Source

Thrown at framework/base/Theme.php:175

            }
        }

        return $path;
    }

    /**
     * Converts a relative URL into an absolute URL using [[baseUrl]].
     * @param string $url the relative URL to be converted.
     * @return string the absolute URL
     * @throws InvalidConfigException if [[baseUrl]] is not set
     */
    public function getUrl($url)
    {
        if (($baseUrl = $this->getBaseUrl()) !== null) {
            return $baseUrl . '/' . ltrim($url, '/');
        }

        throw new InvalidConfigException('The "baseUrl" property must be set.');
    }

    /**
     * Converts a relative file path into an absolute one using [[basePath]].
     * @param string $path the relative file path to be converted.
     * @return string the absolute file path
     * @throws InvalidConfigException if [[basePath]] is not set
     */
    public function getPath($path)
    {
        if (($basePath = $this->getBasePath()) !== null) {
            return $basePath . DIRECTORY_SEPARATOR . ltrim($path, '/\\');
        }

        throw new InvalidConfigException('The "basePath" property must be set.');
    }
}

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Add baseUrl to the theme config: 'baseUrl' => '@web/themes/basic'.
2. Or replace theme->getUrl() calls with direct asset URLs or an AssetBundle, which is the recommended way to publish theme assets in Yii2.
3. Guard shared helpers: if (Yii::$app->view->theme !== null && Yii::$app->view->theme->getBaseUrl() !== null) before calling getUrl().

Example fix

// before
'view' => ['theme' => ['pathMap' => ['@app/views' => '@app/themes/basic/views']]],
echo $view->theme->getUrl('css/main.css'); // baseUrl never set -> throws

// after
'view' => ['theme' => [
    'pathMap' => ['@app/views' => '@app/themes/basic/views'],
    'baseUrl' => '@web/themes/basic',
]],
echo $view->theme->getUrl('css/main.css');

$theme = Yii::$app->view->theme;
if ($theme === null || $theme->getBaseUrl() === null) {
    $url = Yii::getAlias('@web') . '/themes/default/' . ltrim($path, '/'); // fallback URL
} else {
    $url = $theme->getUrl($path);
}

When it happens

Trigger: Calling $view->theme->getUrl('css/main.css') in a layout while the theme was configured with only basePath/pathMap; using Theme::getUrl() in a view helper on a theme instantiated inline with new Theme() and no baseUrl; theme config key misspelled ('baseurl') so the setter never ran.

Common situations: A theme set up purely for view-file replacement (pathMap) while some layout still calls $this->theme->getUrl() for asset links; helper code shared across apps where one app's theme lacks baseUrl; config refactor that dropped the baseUrl line unnoticed because view rendering still worked.

Related errors

• The "basePath" property must be set.
• Cost must be between 4 and 31.
• Unsupported type '{type}'
• DbDependency::sql must be set.
• "{class}::$query" should be an instance of "yii\db\QueryInte

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