{"record":{"id":"cd8af533d3f47fa5","repo":"octobercms/october","slug":"cms-lang-ajax-handler-not-found","errorCode":null,"errorMessage":"cms::lang.ajax_handler.not_found","messagePattern":"cms::lang\\.ajax_handler\\.not_found","errorType":"exception","errorClass":"CmsException","httpStatus":null,"severity":"error","filePath":"modules/cms/classes/controller/HasAjaxRequests.php","lineNumber":146,"sourceCode":"            // Validates the handler partial list\n            $partialList = $this->getAjaxHandlerPartialList();\n\n            // Execute the handler\n            $result = null;\n            if ($this->partialWatcher) {\n                if ($exception = $this->partialWatcher->getHandlerException()) {\n                    throw $exception;\n                }\n\n                $result = $this->partialWatcher->getHandlerResponse();\n            }\n\n            if (!$result) {\n                $result = $this->runAjaxHandler($handler);\n            }\n\n            if (!$result) {\n                throw new CmsException(Lang::get('cms::lang.ajax_handler.not_found', ['name'=>e($handler)]));\n            }\n\n            $response = $result && $result !== true ? ajax()::wrap($result) : ajax();\n\n            // Include partials\n            if ($partialList = $this->ajaxRequest->partialList) {\n                foreach ($partialList as $partial) {\n                    $partialContents = null;\n                    if ($this->partialWatcher) {\n                        $partialContents = $this->partialWatcher->getPartialContents($partial);\n                    }\n                    if (!$partialContents) {\n                        $partialContents = $this->renderPartial($partial);\n                    }\n                    $response->partial($partial, $partialContents);\n                }\n            }\n        }","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/cms/classes/controller/HasAjaxRequests.php#L128-L164","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the handler method exists in this page's code section, its layout's code section, or the partial currently rendering (partial stack)","Check the component is attached to the page and its alias matches the 'alias::onX' reference exactly (case-sensitive)","If you intercept via cms.ajax.beforeRunHandler, return a truthy value when you handle the request","Make sure the handler is public and correctly named onX"],"exampleFix":"<!-- before: markup uses 'cart' but the component alias is 'cartComp' -->\n<button data-request=\"cart::onAdd\">Add</button>\n\n<!-- after -->\n<button data-request=\"cartComp::onAdd\">Add</button>","handlingStrategy":"validation","validationCode":"// in page code, before rendering markup that fires alias::onFoo:\n$component = $this->components['alias'] ?? null;\nif (!$component || !method_exists($component, 'onFoo')) {\n    // component not attached or handler missing: render a safe fallback or log it\n}","typeGuard":null,"tryCatchPattern":"try { $.request('alias::onFoo'); } catch (e) { /* verify the component alias on this page and that onFoo exists, then fix the reference */ }","preventionTips":["After moving/renaming handlers, grep both markup (data-request) and code sections","Keep component aliases stable once pages reference them","Ensure every page using component AJAX actually attaches that component"],"tags":["ajax","handler","cms","routing","winter-cms"],"backgroundTag":"handler-not-found","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}