What causes "cms::lang.layout.not_found_name" in octobercms/october?

Edit the page in the CMS backend and set its Layout field to an existing layout (or '— no layout —' to use the fallback layout).

octobercms/october · error · CmsException

cms::lang.layout.not_found_name

Error message

cms::lang.layout.not_found_name

What it means

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.

Source

Thrown at modules/cms/classes/Controller.php:315

     * @return string
     */
    public function runPage($page, $options = [])
    {
        // Process options
        extract(array_merge([
            'capture' => false,
            'render' => false
        ], (array) $options));

        $useAjax = !($capture || $render);

        // If the page doesn't refer any layout, create the fallback layout.
        // Otherwise load the layout specified in the page.
        if (!$page->layout) {
            $layout = Layout::initFallback($this->theme);
        }
        elseif (($layout = Layout::loadCached($this->theme, $page->layout)) === null) {
            throw new CmsException(Lang::get('cms::lang.layout.not_found_name', ['name' => $page->layout]));
        }

        $this->page = $page;
        $this->layout = $layout;
        $this->pageCycled = false;

        // The 'this' variable is reserved for default variables.
        $this->vars['this'] = new ThisVariable([
            'controller' => $this,
            'page' => $this->page,
            'layout' => $this->layout,
            'theme' => $this->theme,
            'param' => $this->router->getParameters(),
            'environment' => fn() => App::environment(),
            'request' => fn() => App::make('request'),
            'session' => fn() => App::make('session')->driver(),
            'site' => fn() => Site::getActiveSite(),
            'locale' => fn() => App::getLocale(),

View on GitHub (pinned to b608633a7e)

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.

Example fix

; --- page front-matter (themes/mytheme/pages/about.htm) ---
; before
url = "/about"
layout = "main"

; after (file exists at themes/mytheme/layouts/default.htm)
url = "/about"
layout = "default"

Defensive patterns

Strategy: validation

Validate before calling

use Cms\Classes\Layout;
use Cms\Classes\Page;

$page = Page::loadCached($theme, 'about.htm');
if ($page && $page->layout && Layout::loadCached($theme, $page->layout) === null) {
    // resolve before rendering: fix the reference or fall back
    $page->layout = null; // null triggers Layout::initFallback in the controller
}

Try / catch

try {
    return Controller::getController()->runPage($page);
} catch (Cms\Classes\CmsException $e) {
    // log the layout name, render a themed 500 instead of a hard failure
    Log::error('Page render failed: ' . $e->getMessage());
    return Response::view('errors.500', [], 500);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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