What causes "File missing from request" in octobercms/october?

Raise PHP limits: upload_max_filesize and post_max_size (post_max_size must exceed the file size), plus client_max_body_size in nginx / LimitRequestBody in Apache, then restart PHP-FPM.

octobercms/october · error · ApplicationException

File missing from request

Error message

File missing from request

What it means

ApplicationException thrown at MediaManager.php:1568 when the upload AJAX request reaches the handler without any file under the 'file_data' field (Input::hasFile('file_data') is false). The widget already checked the mediaCreate permission and set the locale, so the request itself authenticated fine — the multipart payload simply contained no file.

Source

Thrown at modules/media/widgets/MediaManager.php:1568

        $quickMode = false;

        if (
            (!($uniqueId = Request::header('X-OCTOBER-FILEUPLOAD')) || $uniqueId !== $this->getId()) &&
            (!$quickMode = post('X_OCTOBER_MEDIA_MANAGER_QUICK_UPLOAD'))
        ) {
            return;
        }

        // Set locale early since this runs in the widget constructor,
        // before the controller applies the user's locale preference
        \Backend\Models\Preference::setAppLocale();

        if (!$this->checkHasPermission('mediaCreate')) {
            throw new ForbiddenException;
        }

        if (!Input::hasFile('file_data')) {
            throw new ApplicationException('File missing from request');
        }

        try {
            $uploadedFile = files('file_data');

            /**
             * @event media.file.beforeUpload
             * Called before a file is uploaded
             *
             * Example usage:
             *
             *     Event::listen('media.file.beforeUpload', function ((\Symfony\Component\HttpFoundation\File\UploadedFile) $uploadedFile) {
             *         \Log::info($path . " was uploaded.");
             *     });
             *
             * Or
             *
             *     $mediaWidget->bindEvent('file.beforeUpload', function ((\Symfony\Component\HttpFoundation\File\UploadedFile) $uploadedFile) {

View on GitHub (pinned to b608633a7e)

Solutions

Raise PHP limits: upload_max_filesize and post_max_size (post_max_size must exceed the file size), plus client_max_body_size in nginx / LimitRequestBody in Apache, then restart PHP-FPM.
Ensure the client sends multipart/form-data with the field named exactly 'file_data' (this is Froala's imageParamName default wiring in the media manager).
For custom code, append the File/Blob to FormData under the 'file_data' key before the request.

Example fix

// before (custom uploader)
const fd = new FormData();
fd.append('upload', file);

// after
const fd = new FormData();
fd.append('file_data', file);

Defensive patterns

Strategy: validation

Validate before calling

// Client-side, before upload
if (!(file instanceof File) || file.size === 0) {
    alert('No file selected.');
    return;
}
const fd = new FormData();
fd.append('file_data', file);
fd.append('path', currentPath);

Type guard

function hasUploadFile(form, field = 'file_data') {
    const input = form.elements[field];
    return !!input && !!input.files && input.files.length > 0 && input.files[0].size > 0;
}

Try / catch

try {
    await $.request('onUpload', { data: fd });
} catch (e) {
    // Empty $_FILES usually means the body exceeded post_max_size
    if (/File missing from request/.test(e.responseText || '')) {
        alert('File too large for the server limit (post_max_size).');
    }
}

Prevention

Set upload_max_filesize and post_max_size above your largest expected asset, and nginx client_max_body_size above post_max_size.
Always use multipart/form-data with the field name file_data.
Client-side, reject files above the documented server limit before uploading.

When it happens

Trigger: Uploading via onUpload with a wrong field name, a JSON body instead of multipart/form-data, or — the classic case — a file that exceeds PHP's post_max_size, which causes PHP to drop the entire $_FILES/$_POST array so the request looks empty. The handler is also used for Froala image uploads, which must use the file_data param name.

Common situations: Uploading large videos/images where upload_max_filesize or post_max_size (and nginx client_max_body_size) are too small; custom upload forms renaming the input; JS sending FormData without the file appended; reverse proxies stripping the body.

Related errors

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