{"record":{"id":"cf5f85cafe57d815","repo":"octobercms/october","slug":"unable-to-set-active-theme-missing-a-site-definit","errorCode":null,"errorMessage":"Unable to set active theme. Missing a site definition.","messagePattern":"Unable to set active theme\\. Missing a site definition\\.","errorType":"exception","errorClass":"ApplicationException","httpStatus":null,"severity":"error","filePath":"modules/cms/classes/Theme.php","lineNumber":237,"sourceCode":"        return self::$activeThemeCache = $theme;\n    }\n\n    /**\n     * setActiveTheme sets the active theme\n     *\n     * The active theme code is stored in the database and overrides the\n     * configuration cms.active_theme config item.\n     */\n    public static function setActiveTheme(string $code)\n    {\n        $theme = static::load($code);\n        if ($theme->isLocked()) {\n            throw new ApplicationException(Lang::get('cms::lang.theme.active.is_locked', ['theme' => $code]));\n        }\n\n        $site = App::runningInBackend() ? Site::getEditSite() : Site::getPrimarySite();\n        if (!$site) {\n            throw new ApplicationException(__(\"Unable to set active theme. Missing a site definition.\"));\n        }\n\n        Db::table($site->getTable())->where('id', $site->id)->update(['theme' => $code]);\n        Config::set('cms.active_theme', $code);\n\n        self::resetCache();\n\n        /**\n         * @event cms.theme.setActiveTheme\n         * Fires when the active theme has been changed.\n         *\n         * Example usage:\n         *\n         *     Event::listen('cms.theme.setActiveTheme', function ($code) {\n         *         \\Log::info(\"Theme has been changed to $code\");\n         *     });\n         *\n         */","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/cms/classes/Theme.php#L219-L255","documentation":"ApplicationException thrown by `Theme::setActiveTheme()` when the site lookup fails: `Site::getEditSite()` (backend context) or `Site::getPrimarySite()` (other contexts) returned null. Winter CMS stores the active theme on the site record, so without a site row the update target is unknown and the operation aborts before touching the database.","triggerScenarios":"Calling setActiveTheme() on an installation whose sites table is empty or missing — migrations never run, database truncated/restored without seed data, or a console command running where no primary site is defined.","commonSituations":"Partial deployments where `php artisan migrate` was skipped; staging databases copied without seed rows; custom installers that create config but not the primary site; multi-site plugins whose setup step was missed.","solutions":["Run the full setup/migrations: `php artisan winter:up` (or `php artisan migrate --seed`) so the primary site row exists.","Verify with a tinker check: `Site::getPrimarySite()` should return a model, not null.","If the site row was soft-deleted or corrupted, recreate it via the backend multi-site settings."],"exampleFix":"# before — sites table empty, setActiveTheme() aborts\n$ php artisan tinker\n>>> Site::getPrimarySite()   # null\n\n# after — create/migrate the site records\n$ php artisan winter:up\n>>> Site::getPrimarySite()   # returns the primary site model","handlingStrategy":"validation","validationCode":"use System\\Models\\Site; // winter multi-site\n\n$site = app()->runningInBackend() ? Site::getEditSite() : Site::getPrimarySite();\nif (!$site) {\n    return back()->with('error', 'No site record found. Run `php artisan winter:up` before changing the theme.');\n}\nTheme::setActiveTheme($code);","typeGuard":null,"tryCatchPattern":"try {\n    Theme::setActiveTheme($code);\n} catch (ApplicationException $e) {\n    if (str_contains($e->getMessage(), 'site definition')) {\n        // DB not provisioned: point the operator at setup instead of failing silently\n        Log::critical('setActiveTheme blocked: no site record');\n        return redirect()->to('/backend/system/updates');\n    }\n    throw $e;\n}","preventionTips":["Make `winter:up` (migrations + seed) a mandatory step in every deployment runbook.","Add a post-deploy check that Site::getPrimarySite() is non-null before enabling the app.","When copying databases between environments, verify the sites table came across."],"tags":["multisite","database","theme","missing-record"],"backgroundTag":"missing-database-record","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}