Docs

Automatic offloading

5 min readUpdated November 9, 2026

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#

Offload Behaviour card with Offload on upload
  1. In your WordPress admin, go to Media Cloud > Settings.
  2. Find the Offload Behaviour card.
  3. Switch Offload on upload on or off.
  4. 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 uploadedWhen it goes to the cloud
Block editor, media modal, featured image picker, and other REST API uploadsStraight away, so the editor receives the CDN URL in its response
Media Library uploader and other uploadsAt the end of the same request, after every other plugin has finished with the file
Anything the first two missedA 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, medium and large;
  • the original image, when WordPress kept one next to a -scaled version 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#

Bulk Offload card on the Dashboard

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 failed lists failed items. wp wpmc offload --retry-failed retries 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 seeWhat it meansHow to fix it
Not configured in the Media LibraryThe storage provider settings are incompleteFinish the setup wizard or add the missing values in Settings
Offload failed with a reasonThe provider refused the upload, the file was missing on disk, or the network failedFix the cause in the reason, then click Retry
New uploads stay local, no error shownOffload on upload is offSwitch 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.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only