{"record":{"id":"dbf973e47c9e327c","repo":"octobercms/october","slug":"cms-lang-layout-not-found-name","errorCode":null,"errorMessage":"cms::lang.layout.not_found_name","messagePattern":"cms::lang\\.layout\\.not_found_name","errorType":"exception","errorClass":"CmsException","httpStatus":null,"severity":"error","filePath":"modules/cms/classes/Controller.php","lineNumber":315,"sourceCode":"     * @return string\n     */\n    public function runPage($page, $options = [])\n    {\n        // Process options\n        extract(array_merge([\n            'capture' => false,\n            'render' => false\n        ], (array) $options));\n\n        $useAjax = !($capture || $render);\n\n        // If the page doesn't refer any layout, create the fallback layout.\n        // Otherwise load the layout specified in the page.\n        if (!$page->layout) {\n            $layout = Layout::initFallback($this->theme);\n        }\n        elseif (($layout = Layout::loadCached($this->theme, $page->layout)) === null) {\n            throw new CmsException(Lang::get('cms::lang.layout.not_found_name', ['name' => $page->layout]));\n        }\n\n        $this->page = $page;\n        $this->layout = $layout;\n        $this->pageCycled = false;\n\n        // The 'this' variable is reserved for default variables.\n        $this->vars['this'] = new ThisVariable([\n            'controller' => $this,\n            'page' => $this->page,\n            'layout' => $this->layout,\n            'theme' => $this->theme,\n            'param' => $this->router->getParameters(),\n            'environment' => fn() => App::environment(),\n            'request' => fn() => App::make('request'),\n            'session' => fn() => App::make('session')->driver(),\n            'site' => fn() => Site::getActiveSite(),\n            'locale' => fn() => App::getLocale(),","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/cms/classes/Controller.php#L297-L333","documentation":"Thrown by the CMS Controller while rendering a front-end page: the page's front-matter sets `layout = X`, but `Layout::loadCached($theme, X)` returned null, meaning no layout with that base file name exists in the active theme's `layouts/` directory. Rendering aborts with a CmsException instead of using an unknown wrapper. Only a missing/empty `layout` value falls back to `Layout::initFallback`; a non-empty name that doesn't resolve is fatal.","triggerScenarios":"Opening any URL whose CMS page declares `layout: main` when `themes/<active-theme>/layouts/main.htm` does not exist (deleted, renamed, or never deployed); switching the active theme to one that lacks the layout referenced by the page; stale CMS layout cache after a git pull that renamed layouts.","commonSituations":"Layout renamed but pages not updated; new theme selected on a multi-theme site where page definitions reference the old theme's layouts; layout file not committed to git so production lacks it; case-sensitivity mismatch (Layout.htm vs layout.htm) moving from macOS/Windows to Linux.","solutions":["Edit the page in the CMS backend and set its Layout field to an existing layout (or '— no layout —' to use the fallback layout).","Create or rename the layout file under themes/<active-theme>/layouts/ so its base file name matches the page's `layout` value exactly.","Verify the active theme is the one you expect: check `cms.active_theme` config and the site record; the layout must exist in that theme.","Clear the CMS cache (php artisan cache:clear / cms.cache clear) if the layout file exists but was added after the cached lookup."],"exampleFix":"; --- page front-matter (themes/mytheme/pages/about.htm) ---\n; before\nurl = \"/about\"\nlayout = \"main\"\n\n; after (file exists at themes/mytheme/layouts/default.htm)\nurl = \"/about\"\nlayout = \"default\"","handlingStrategy":"validation","validationCode":"use Cms\\Classes\\Layout;\nuse Cms\\Classes\\Page;\n\n$page = Page::loadCached($theme, 'about.htm');\nif ($page && $page->layout && Layout::loadCached($theme, $page->layout) === null) {\n    // resolve before rendering: fix the reference or fall back\n    $page->layout = null; // null triggers Layout::initFallback in the controller\n}","typeGuard":null,"tryCatchPattern":"try {\n    return Controller::getController()->runPage($page);\n} catch (Cms\\Classes\\CmsException $e) {\n    // log the layout name, render a themed 500 instead of a hard failure\n    Log::error('Page render failed: ' . $e->getMessage());\n    return Response::view('errors.500', [], 500);\n}","preventionTips":["When renaming a layout, grep all pages' front-matter for the old name and update them in the same commit.","Add a deploy check that every page's `layout` value exists in the target theme's layouts/ directory.","Keep layout names lowercase and consistent to avoid case-sensitivity breakage between dev (macOS/Windows) and prod (Linux).","Run the same theme set in all environments so a missing layout surfaces in CI, not production."],"tags":["cms","layout","theme","rendering","template-not-found"],"backgroundTag":"template-not-found","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}