octobercms/october · error · ApplicationException

A media file already exists at this location, please upload

Error message

A media file already exists at this location, please upload using a different filename.

What it means

ApplicationException thrown at MediaManager.php:1707 by the exists-check helper during upload when a file with the same name already exists in the target folder AND the overwrite path is unavailable: force_overwrite was not posted or the user lacks the mediaDelete permission (overwriting is treated as deletion). For the Froala rich-editor flow the same condition instead returns an HTTP 200 JSON error so the editor can display it inline.

Source

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

                $this->controller->setResponse(Response::make([
                    'link' => MediaLibrary::url($filePath),
                    'result' => 'success'
                ]));
                return true;
            }

            // Different content with same filename: return error as HTTP 200 JSON so Froala's
            // image.uploaded event can intercept and show a meaningful message to the user
            $this->controller->setResponse(Response::make([
                'error' => Lang::get('backend::lang.media.folder_or_file_exist')
            ]));
            return true;
        }

        $forceOverwrite = (bool) post('force_overwrite', false);
        $canOverwrite = $this->checkHasPermission('mediaDelete');
        if (!$canOverwrite || !$forceOverwrite) {
            throw new ApplicationException(__('A media file already exists at this location, please upload using a different filename.'));
        }

        return false;
    }

    /**
     * validateFileName validates a proposed media item file name.
     * @param string $name
     * @return bool
     */
    protected function validateFileName(string $name): bool
    {
        // Reject invalid encoding, path separators and reserved characters
        if (!preg_match('/^[^\/\\\\<>:"|?*]+$/u', $name)) {
            return false;
        }

        // Reject control, format and other invisible characters

View on GitHub (pinned to b608633a7e)

Solutions

1. Upload under a different filename, or delete/rename the existing item first.
2. Enable overwrite when the user is allowed: grant the media.delete permission to the role AND post force_overwrite=true from the upload UI.
3. Turn on automatic renaming (config media.auto_rename set to 'slug' plus your own uniqueness step) or have the client append a suffix before upload.

Example fix

// before
$.request('onUpload', { data: { path: '/blog', file_data: file } });

// after
$.request('onUpload', { data: { path: '/blog', file_data: file, force_overwrite: true } });
// (requires the user to have the media delete permission)

// Before upload, check for a collision and decide the strategy
const exists = await checkFileExists(currentPath, file.name);
if (exists && !userCanDelete) {
    file = new File([file], uniqueName(file.name), { type: file.type }); // rename client-side
}

function canOverwrite(userHasMediaDelete, forceOverwritePosted) {
    return userHasMediaDelete && forceOverwritePosted === true;
}

try {
    await $.request('onUpload', { data: fd });
} catch (e) {
    if (/already exists/.test(e.responseText || '')) {
        fd.append('force_overwrite', 'true'); // only if user has media delete permission
        await $.request('onUpload', { data: fd });
    }
}

When it happens

Trigger: POSTing onUpload with path '/x' and a filename that already exists, without post('force_overwrite', true), or with force_overwrite set while the authenticated user has no media.delete permission. Froala uploads of an image re-inserted at the same name hit the JSON-error branch.

Common situations: Re-uploading an updated image with the same name (very common for hero/logo images); bulk uploads that collide with existing names; auto_rename not enabled (media.auto_rename === 'slug' only slugs the name, it does not make it unique).

Related errors

• backend::lang.media.error_creating_folder
• Error saving remote file to a temporary location
• Error creating thumbnail directory
• File missing from request
• The file type used is blocked for security reasons.

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