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

Create themes/ /partials/ .htm or correct the reference path

octobercms/october · error · CmsException

cms::lang.partial.not_found_name

Error message

cms::lang.partial.not_found_name

What it means

renderPartial() (backing the {% partial %} tag) could not find the named partial in the current theme — neither from a cms.page.beforeRenderPartial event override nor from the theme datasource — and was invoked with $throwException = true, the default for the Twig tag.

Source

Thrown at modules/cms/classes/controller/HasRenderers.php:180

         *     });
         *
         * Or
         *
         *     $controller->bindEvent('page.beforeRenderPartial', function ((string) $partialName) {
         *         return Cms\Classes\Partial::loadCached($theme, 'custom-partial-name');
         *     });
         *
         */
        if ($event = $this->fireSystemEvent('cms.page.beforeRenderPartial', [$name])) {
            $partial = $event;
        }
        else {
            $partial = $this->loadPartialObject($name, $throwException);
        }

        if ($partial === false) {
            if ($throwException) {
                throw new CmsException(Lang::get('cms::lang.partial.not_found_name', ['name'=>$name]));
            }
            else {
                return false;
            }
        }

        // Run functions for CMS partials only (Cms\Classes\Partial)
        if ($partial instanceof Partial) {
            if (!$this->partialStack) {
                $this->partialStack = new PartialStack;
            }
            $this->partialStack->stackPartial();

            foreach ($partial->settings['components'] as $component => $properties) {
                // Do not inject the viewBag component to the environment.
                // Not sure if they're needed there by the requirements,
                // but there were problems with array-typed properties used by Static Pages
                // snippets and parseRouteParamsOnComponent(). --ab

View on GitHub (pinned to b608633a7e)

Solutions

Create themes/<activeTheme>/partials/<name>.htm or correct the reference path
Check letter casing exactly — partial names are case-sensitive on Linux
Confirm Theme::getActiveThemeCode() points at the theme that actually contains the partial
For optional partials, call renderPartial($name, [], false) and handle the false return instead of letting it throw

Example fix

{# before #}
{% partial 'price_card' %}

{# after #}
{% partial 'cards/price' %}

Defensive patterns

Strategy: validation

Validate before calling

$theme = \Cms\Classes\Theme::getActiveTheme();
if (!\Cms\Classes\Partial::load($theme, 'cards/price')) {
    // partial missing: skip the block, use a fallback partial, or fail with context
}

Try / catch

try { echo $this->renderPartial('cards/price'); } catch (\Cms\Classes\CmsException $e) { echo '<!-- partial missing -->'; }

Prevention

Use exact-case paths matching the filesystem, including subfolders
Run a reference check (grep) for every partial name before renaming or moving it
Develop on a case-sensitive filesystem or enable case-sensitivity checks in CI

When it happens

Trigger: {% partial 'cards/price' %} or $this->renderPartial('cards/price') when themes/<activeTheme>/partials/cards/price.htm does not exist; renamed subfolders; casing mismatch; the active theme switched so the partial is absent.

Common situations: Refactoring partial folders without updating references; developing on case-insensitive macOS/Windows and deploying to Linux; referencing partials belonging to another theme; database-layer templates missing the file copy.

Related errors

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