{"record":{"id":"a711b8e716d127ed","repo":"getgrav/grav","slug":"theme-theme-could-not-be-found","errorCode":null,"errorMessage":"{theme} theme could not be found","messagePattern":"(.+?) theme could not be found","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"system/src/Grav/Common/Themes.php","lineNumber":81,"sourceCode":"        $themes = $this->grav['themes'];\n        $themes->configure();\n\n        $this->initTheme();\n    }\n\n    /**\n     * @return void\n     */\n    public function initTheme()\n    {\n        if ($this->inited === false) {\n            /** @var Themes $themes */\n            $themes = $this->grav['themes'];\n\n            try {\n                $instance = $themes->load();\n            } catch (InvalidArgumentException) {\n                throw new RuntimeException($this->current() . ' theme could not be found');\n            }\n\n            // Register autoloader.\n            if (method_exists($instance, 'autoload')) {\n                $instance->autoload();\n            }\n\n            // Register event listeners.\n            if ($instance instanceof EventSubscriberInterface) {\n                /** @var EventDispatcher $events */\n                $events = $this->grav['events'];\n                $events->addSubscriber($instance);\n            }\n\n            // Register blueprints.\n            if (is_dir('theme://blueprints/pages')) {\n                /** @var UniformResourceLocator $locator */\n                $locator = $this->grav['locator'];","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/getgrav/grav/blob/6040efed04efa69b8209448ed81308e7c24147c2/system/src/Grav/Common/Themes.php#L63-L99","documentation":"Thrown by Themes::initTheme() when $themes->load() fails with an InvalidArgumentException while resolving the current theme through the theme:// stream. It means the theme configured as current (system.pages.theme) could not be located or loaded, so the frontend has nothing to render with. Grav deliberately keeps admin and API requests alive when a theme is missing (load() closes with a 500 only for frontend requests), so hitting this RuntimeException usually means the theme stream itself failed to resolve the theme's files.","triggerScenarios":"system.pages.theme: mytheme in user/config/system.yaml while user/themes/mytheme/ does not exist; theme folder renamed or with different letter-case on a case-sensitive filesystem; a theme installed from a GitHub zip as mytheme-master while config expects mytheme; theme files missing after a git clone because user/themes was gitignored; a broken theme:// stream registration produced by bad streams.schemes config.","commonSituations":"Moving a site between environments without vendoring themes; deleting a still-selected theme from the admin; typos or case mismatches between the configured theme name and the installed folder name; deploying partial artifacts that omit user/themes.","solutions":["Compare the value of pages.theme in user/config/system.yaml with the folder names under user/themes/ and make them match exactly (case included)","Install or restore the theme: bin/gpm install <name>, or re-upload it so the folder name equals the theme name","Rename the mismatched folder (mv user/themes/mytheme-master user/themes/mytheme) and run bin/grav clearcache","If the admin backend is reachable, temporarily switch to an installed theme (e.g. quark) and fix the missing one at leisure"],"exampleFix":"# before: system.yaml has pages.theme: quark but the folder is quark-master\nuser/themes/quark-master/quark-master.yaml\n\n# after\nmv user/themes/quark-master user/themes/quark\nbin/grav clearcache","handlingStrategy":"validation","validationCode":"// verify the configured theme exists before init\n$name = $grav['config']->get('system.pages.theme');\n$locator = $grav['locator'];\nif (!$name || !$locator->findResource(\"themes://{$name}\", true)) {\n    // fail fast with an actionable message or fall back to a known-good theme\n    $grav['config']->set('system.pages.theme', 'quark');\n}","typeGuard":null,"tryCatchPattern":"try { $themes->initTheme(); } catch (RuntimeException $e) { // render maintenance page, log theme name\n    echo 'Theme unavailable: ' . $e->getMessage(); }","preventionTips":["Keep themes inside the deploy artifact; do not gitignore user/themes on servers","Assert folder name equals the theme name exactly (case included) in CI","Clear cache after switching themes","Keep the admin plugin installed so a broken theme is recoverable from the backend"],"tags":["theme","configuration","installation","frontend"],"backgroundTag":"theme-not-found","analyzedSha":"6040efed04efa69b8209448ed81308e7c24147c2","analyzedAt":"2026-08-17T05:07:31.593Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}