Automatic offloading
WP Media Cloud copies every new Media Library upload to your cloud storage as soon as WordPress has finished processing it. This page explains when that happens, what gets uploaded, and what happens when an upload fails.
Turn it on or off#

- In your WordPress admin, go to Media Cloud > Settings.
- Find the Offload Behaviour card.
- Switch Offload on upload on or off.
- Click Save Settings.
Offload on upload is on by default. It only works once a storage provider is fully configured. Until then, uploads stay on your server and the Media Library shows Not configured next to each file.
When you switch it off, new uploads stay on your server. Files that are already offloaded keep loading from your CDN, because serving is controlled by Rewrite URLs, not by this switch. See URL rewriting.
If you updated from a version older than 1.1.7.1, check this switch and Rewrite URLs once. In those versions, finishing the setup wizard could switch both off.
When a file is offloaded#
| How the file was uploaded | When it goes to the cloud |
|---|---|
| Block editor, media modal, featured image picker, and other REST API uploads | Straight away, so the editor receives the CDN URL in its response |
| Media Library uploader and other uploads | At the end of the same request, after every other plugin has finished with the file |
| Anything the first two missed | A WP-Cron check about 5 minutes after the upload offloads it if it is still local |
WP Media Cloud waits until WordPress has generated all image sizes. This lets image optimizers and file rename plugins finish first.
Image optimizers#
Some optimizers compress images in the background. These are EWWW Image Optimizer, Imagify, Smush and ShortPixel. WP Media Cloud uploads the original first, so the editor gets a CDN URL at once.
When the optimizer reports that it has finished, WP Media Cloud uploads the compressed version again.
For a short time, usually under a minute, the uncompressed file is live on your CDN. The file size shown in the media modal can also be the original size until you refresh it.
What gets uploaded#
For each attachment, WP Media Cloud uploads:
- the main file;
- every image size WordPress generated, such as
thumbnail,mediumandlarge; - the original image, when WordPress kept one next to a
-scaledversion of a large photo.
Each file keeps its path inside the uploads folder. For example, wp-content/uploads/2026/10/photo.jpg is stored as 2026/10/photo.jpg in your bucket.
To store files in a folder of the bucket, such as media/2026/10/photo.jpg, set a Path prefix. See Custom path prefix.
Every file is stored with the header Cache-Control: public, max-age=31536000, immutable. CDNs and browsers can then cache it for a year. When a file is re-uploaded under the same name, for example after an image optimizer compresses it, CDNs and browsers may keep the earlier copy. Purge it from your CDN.
What is not offloaded#
Only attachments in the WordPress Media Library are offloaded. These files stay on your server:
- theme and plugin files;
- files you copy to the server by FTP or SFTP without adding them to the Media Library;
- files plugins store outside the Media Library, such as BuddyBoss avatars and cover photos, cache folders and some form uploads;
- media uploaded before you installed WP Media Cloud. Use the Bulk migration tool for these.
Some Media Library files are kept on your server on purpose:
- font files (
.woff2,.woff,.ttf,.otf,.eot), while Serve fonts from your site is on, the default. See Serve fonts from your site; - videos sent to Bunny Stream;
- protected store files, such as WooCommerce and Easy Digital Downloads product files, when secure downloads are off or your storage cannot keep them private.
These show Offload now in the Media Library list, but are skipped when offloaded by any route.
When an upload fails#

If the upload of the main file fails, the attachment stays on your server and is served from your site as before. The uploader does not see an error. WP Media Cloud records the reason on the attachment.
You can see failed files in these places:
- Media > Library in list view: the row shows Offload failed with a Retry link. Hover over the message to see the reason.
- The attachment details: the WP Media Cloud field shows Failed: and the reason, with a Retry link.
- Media Cloud > Dashboard: the Bulk Offload card lists failed items with Retry all and Clear buttons.
- WP-CLI:
wp wpmc failedlists failed items.wp wpmc offload --retry-failedretries them.
The WP-Cron check 5 minutes after the upload tries once more. After that, failed files are retried only when you use one of the options above or run a bulk offload.
Media that was never offloaded, for example because Offload on upload was off, shows an Offload now link in the Media Library list view.
| What you see | What it means | How to fix it |
|---|---|---|
| Not configured in the Media Library | The storage provider settings are incomplete | Finish the setup wizard or add the missing values in Settings |
| Offload failed with a reason | The provider refused the upload, the file was missing on disk, or the network failed | Fix the cause in the reason, then click Retry |
| New uploads stay local, no error shown | Offload on upload is off | Switch it on in Settings > Offload Behaviour |
To see more detail, turn on WP_DEBUG and WP_DEBUG_LOG in wp-config.php. WP Media Cloud then writes lines that start with [WPMC] to the debug log.
Keeping or removing the local copy#
By default, the local copy stays on your server after it is offloaded. To delete it and save disk space, see Local file removal.