octobercms/october · error · Error

Invalid handler name. The correct handler name format is…

Error message

Invalid handler name. The correct handler name format is: "onEvent".

What it means

Sentinel guard at the top of uploadAjaxRequest: before an XHR is opened, the handler string is matched against a regex requiring the 'onEvent' naming convention (optionally namespaced with a '::' prefix, e.g. 'Backend\Classes\Controller::onUpload'); the literal handler 'mediamanager' is also whitelisted. Any handler string that does not start with 'on' (after an optional namespace) fails this check, meaning the AJAX upload request was pointed at a PHP handler method that cannot exist.

Solutions

1. Rename the target PHP handler method to follow the 'onEvent' convention, e.g. onUpload or onSave
2. If the handler lives in another class, use the fully namespaced form 'Vendor\Plugin\Classes\Thing::onUpload'
3. Use the special 'mediamanager' handler only for media manager uploads

When it happens

Trigger: Thrown at modules/backend/vuecomponents/uploader/assets/js/queue.js:5 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at modules/backend/vuecomponents/uploader/assets/js/queue.js:5

import PQueue from 'p-queue';

function uploadAjaxRequest(handler, requestData, onProgress, abortSignal) {
    if (!handler.match(/^(?:\w+\:{2})?on*/) && handler !== 'mediamanager') {
        throw new Error('Invalid handler name. The correct handler name format is: "onEvent".');
    }

    return new Promise((resolve, reject) => {
        if (abortSignal?.aborted) {
            return resolve();
        }

        const xhr = new XMLHttpRequest();
        xhr.open('POST', window.location.href);

        const token = getToken();
        if (token) {
            xhr.setRequestHeader('X-CSRF-TOKEN', token);
        }

        if (handler !== 'mediamanager') {
            xhr.setRequestHeader('X-AJAX-HANDLER', handler);
            xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

View on GitHub (pinned to b608633a7e)