octobercms/october · critical · SystemException

cms::lang.theme.active.not_set

Error message

cms::lang.theme.active.not_set

What it means

SystemException thrown by `Theme::getActiveThemeCode()` when no active theme can be resolved at all: the site record has no theme, there is no backend preview-theme preference, and `cms.active_theme` config is empty/missing. Because every front-end request needs an active theme, this exception typically takes the whole public site down.

Source

Thrown at modules/cms/classes/Theme.php:194

        if ($apiResult !== null) {
            return $apiResult;
        }

        // System edit site override, used for setting the active theme in the backend
        if (App::runningInBackend() && ($siteTheme = Config::get('cms.edit_theme'))) {
            return $siteTheme;
        }

        // Backend preference override, used for setting the preview theme in the editor
        // @todo add a get variable check (_editor_preview)
        if ($prefTheme = self::getEditThemeCodeFromPreference()) {
            return $prefTheme;
        }

        // Config value, used for rendering the frontend
        $activeTheme = Config::get('cms.active_theme');
        if (!$activeTheme) {
            throw new SystemException(Lang::get('cms::lang.theme.active.not_set'));
        }

        return $activeTheme;
    }

    /**
     * getActiveTheme returns the active theme object
     */
    public static function getActiveTheme(): ?Theme
    {
        if (self::$activeThemeCache !== false) {
            return self::$activeThemeCache;
        }

        $theme = static::load($themeCode = static::getActiveThemeCode());

        if ($theme->isLocked()) {
            throw new ApplicationException(Lang::get('cms::lang.theme.active.is_locked', ['theme' => $themeCode]));

View on GitHub (pinned to b608633a7e)

Solutions

1. Set the theme in config/cms.php: 'active_theme' => 'mytheme', or via .env CMS_ACTIVE_THEME=mytheme, then clear config cache.
2. Alternatively set the theme on the site record in the backend (Settings > Theme) which overrides config.
3. Confirm `themes/mytheme/` exists — a configured but missing theme resolves as invalid and leaves the code unset.

Example fix

// .env / config/cms.php — before
CMS_ACTIVE_THEME=

// after — directory themes/mytheme must exist
CMS_ACTIVE_THEME=mytheme
// then: php artisan config:clear

// Boot-time guard (e.g. App boot or a health endpoint)
if (!app()->runningInConsole() && !Config::get('cms.active_theme')) {
    // fail with an actionable setup page instead of an uncaught SystemException
    abort(503, 'No active theme configured. Set CMS_ACTIVE_THEME or choose a theme in the backend.');
}

try {
    $theme = Theme::getActiveTheme();
} catch (System\Exception $e) {
    // active theme unresolvable — render a maintenance/setup page, log for ops
    Log::critical('Active theme not set');
    return response()->view('errors.setup-required', [], 503);
}

When it happens

Trigger: Any front-end request on an installation where config/cms.php lacks 'active_theme', the .env value (CMS_ACTIVE_THEME) is unset, and the site row's theme column is null; after wiping the database while keeping code; config cache poisoned with a null value.

Common situations: Incomplete initial setup; environment variable missing in a new deploy environment; `php artisan config:cache` run with an empty env; site record created without a theme by a custom installer.

Related errors

• cms::lang.theme.edit.not_found
• cms::lang.theme.active.is_locked
• cms::lang.theme.edit.not_set
• Values not found for the selected row.
• Key property ${keyProperty} is not found in the Inspector da

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/90904b3b6c9dafd5. Report an issue: GitHub.