octobercms/october · error · CmsException

cms::lang.ajax_handler.not_found

Error message

cms::lang.ajax_handler.not_found

What it means

The handler name passed the format check, but no handler could be located to run it. runAjaxHandler() searches, in order: the cms.ajax.beforeRunHandler event, attached component methods (alias::onFoo), partial code sections, the page code section, then the layout code section; if nothing matches (or an interceptor returns falsy) the 'AJAX handler not found' CmsException is thrown.

Source

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

            // Validates the handler partial list
            $partialList = $this->getAjaxHandlerPartialList();

            // Execute the handler
            $result = null;
            if ($this->partialWatcher) {
                if ($exception = $this->partialWatcher->getHandlerException()) {
                    throw $exception;
                }

                $result = $this->partialWatcher->getHandlerResponse();
            }

            if (!$result) {
                $result = $this->runAjaxHandler($handler);
            }

            if (!$result) {
                throw new CmsException(Lang::get('cms::lang.ajax_handler.not_found', ['name'=>e($handler)]));
            }

            $response = $result && $result !== true ? ajax()::wrap($result) : ajax();

            // Include partials
            if ($partialList = $this->ajaxRequest->partialList) {
                foreach ($partialList as $partial) {
                    $partialContents = null;
                    if ($this->partialWatcher) {
                        $partialContents = $this->partialWatcher->getPartialContents($partial);
                    }
                    if (!$partialContents) {
                        $partialContents = $this->renderPartial($partial);
                    }
                    $response->partial($partial, $partialContents);
                }
            }
        }

View on GitHub (pinned to b608633a7e)

Solutions

1. Verify the handler method exists in this page's code section, its layout's code section, or the partial currently rendering (partial stack)
2. Check the component is attached to the page and its alias matches the 'alias::onX' reference exactly (case-sensitive)
3. If you intercept via cms.ajax.beforeRunHandler, return a truthy value when you handle the request
4. Make sure the handler is public and correctly named onX

Example fix

<!-- before: markup uses 'cart' but the component alias is 'cartComp' -->
<button data-request="cart::onAdd">Add</button>

<!-- after -->
<button data-request="cartComp::onAdd">Add</button>

// in page code, before rendering markup that fires alias::onFoo:
$component = $this->components['alias'] ?? null;
if (!$component || !method_exists($component, 'onFoo')) {
    // component not attached or handler missing: render a safe fallback or log it
}

try { $.request('alias::onFoo'); } catch (e) { /* verify the component alias on this page and that onFoo exists, then fix the reference */ }

When it happens

Trigger: data-request="onSearch" where onSearch exists only in a different page's code section; data-request="alias::onFoo" where that component is not attached to the current page/layout or the alias is misspelled; the handler lives in a layout the page does not use; a cms.ajax.beforeRunHandler listener returns a falsy value.

Common situations: Copying AJAX-wired markup to a page that lacks the component or handler; renaming a handler in PHP only; component alias changed in the Inspector so the 'alias::' prefix no longer matches; handler moved between page and layout during refactoring.

Related errors

• cms::lang.ajax_handler.invalid_name
• cms::lang.theme.edit.not_set
• Cannot delete the active theme, try making another theme act
• cms::lang.partial.invalid_name
• The request handler name is not specified.

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