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

Use a plain relative path under the theme's partials/ directory, e.g. 'cards/card'

octobercms/october · error · CmsException

cms::lang.partial.invalid_name

Error message

cms::lang.partial.invalid_name

What it means

During an AJAX request, every partial name in the update/partial list is validated by Partial::validateRequestName() before rendering. Valid names are letters, digits, '_', '-', '.', '/' with an optional '@' or 'componentAlias::' prefix; names containing '..', './', '//', spaces or other characters are rejected with this CmsException before the handler response is assembled.

Source

Thrown at modules/cms/classes/controller/HasAjaxRequests.php:101

        // Execute AJAX event
        if ($ajaxResponse = $this->execAjaxHandlers()) {
            return $ajaxResponse;
        }
    }

    /**
     * getAjaxHandlerPartialList
     */
    protected function getAjaxHandlerPartialList(): array
    {
        $request = $this->getAjaxRequest();

        if ($request->hasAjaxHandler()) {
            $partials = $request->partialList;

            foreach ($partials as $partial) {
                if (!Partial::validateRequestName($partial)) {
                    throw new CmsException(Lang::get('cms::lang.partial.invalid_name', ['name'=>e($partial)]));
                }
            }

            return $partials;
        }

        return [];
    }

    /**
     * execAjaxHandlers executes the page, layout, component and plugin AJAX handlers.
     * @return mixed Returns the AJAX Response object or null.
     */
    protected function execAjaxHandlers()
    {
        $handler = $this->getAjaxHandler();
        if (!$handler) {
            return null;

View on GitHub (pinned to b608633a7e)

Solutions

Use a plain relative path under the theme's partials/ directory, e.g. 'cards/card'
Prefix component partials correctly: '@alias/partial' or 'alias::partialname'
Strip any '../', '//' or whitespace from the selector
When issuing requests manually, reuse the data-request/data-request-update API so partial names come from valid template paths

Example fix

<!-- before -->
<div data-request="onSave" data-request-update="../partials/card '#card'"></div>

<!-- after -->
<div data-request="onSave" data-request-update="cards/card '#card'"></div>

Defensive patterns

Strategy: validation

Validate before calling

use \Cms\Classes\Partial;
foreach ($requestPartialList as $name) {
    if (!Partial::validateRequestName($name)) {
        throw new InvalidArgumentException('Invalid partial name: '.$name);
    }
}

Type guard

function isValidPartialName(name) {
  return /^(?:\w+::|@)?[a-z0-9_.\/-]+$/i.test(name) && !name.includes('..') && !name.includes('./') && !name.includes('//');
}

Try / catch

try { $.request(handler, { update: partials }); } catch (e) { /* inspect partial names in the update map, correct and re-issue */ }

Prevention

Generate partial selectors from actual template paths, never concatenate raw user input
Use the framework data-request-update API instead of hand-built partial lists
Add a client-side sanity regex before sending requests when partial names are dynamic

When it happens

Trigger: An AJAX request whose partial update list (data-request-update / the winter.ajax.js partialList) contains a selector like 'my partial', '../theme/partials/x', 'foo//bar', 'foo/bar/', a backslash path, or a misspelled 'Alias::partial' reference.

Common situations: Hand-built AJAX payloads instead of the framework JS; markup copied between projects keeping invalid selectors; partial paths typed with Windows separators or stray whitespace; security probes sending traversal strings.

Related errors

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