Docs

New uploads not being offloaded

5 min readUpdated November 9, 2026

Use this page when files you upload stay on your server instead of going to cloud storage. Work through the checks in order: the switch, the required settings, then the error recorded for the file.

How to see what happened to an upload#

Go to Media > Library and switch to list view. Each row shows the WP Media Cloud status under the file name.

Row statusWhat it meansGo to
In cloudThe file was offloaded.URL rewriting not working if it still loads locally.
Not configuredA required storage setting is empty.Check 2
Not offloaded (not_ready). Offload nowThe file was uploaded while a required setting was empty.Check 2, then click Offload now.
Offload failed. RetryThe upload to storage failed. Hover over it to read the error.Check 3
Offload now onlyWP Media Cloud did not try. Offload on upload is probably off.Check 1
Offload now only, on a font file (.woff2, .woff, .ttf, .otf, .eot)Fonts stay on your server on purpose while Serve fonts from your site is on. They are skipped even when you click Offload now.Nothing to fix. See Serve fonts from your site.

The attachment details screen shows the same information in its WP Media Cloud field.

Check 1: Is Offload on upload switched on?#

Offload Behaviour card with Offload on upload
  1. Go to Media Cloud > Settings.
  2. Under Offload Behaviour, check that Offload on upload is on. Check Rewrite URLs too.
  3. Click Save Settings.

In versions before 1.1.7.1, finishing the setup wizard could switch off Offload on upload and Rewrite URLs. If you ran the wizard on an older version, check both switches now.

Files uploaded while the switch was off stay on your server. Offload them with Offload All Media on the Dashboard, or run wp wpmc offload.

Check 2: Are all required settings filled in?#

Health tab with the Upload Test check

WP Media Cloud only offloads when every required field for your provider has a value. If one is empty, uploads stay local and no error is recorded.

ProviderRequired fields
Bunny.netStorage zone, Zone Password, pull zone
Cloudflare R2Account ID, Access Key ID, Secret Access Key, Bucket name, CDN URL
Amazon S3Region, Access Key ID, Secret Access Key, Bucket name
DigitalOcean SpacesRegion, Access Key, Secret Key, Bucket name
WasabiRegion, Access Key, Secret Key, Bucket name
HetznerRegion, Access Key, Secret Key, Bucket name
Backblaze B2Region, Key ID, Application Key, Bucket name
Google CloudHMAC Access Key, HMAC Secret, Bucket name
Custom S3Endpoint URL, Access Key, Secret Key, Bucket

Cloudflare R2 needs the CDN URL as well as the keys. Without it, R2 uploads do not start.

Values can also come from WPMC_* constants in wp-config.php. A constant always wins over a saved value.

To check:

  1. Go to Health and click Run All Checks.
  2. The Upload Test row says “Plugin not ready: storage credentials are incomplete. Check Settings or run the Setup Wizard.” when a field is missing. The Bucket row names the missing fields for S3-type providers.
  3. Go to Settings and click run the setup wizard. It opens with your current values. Fill in the missing field and save.
  4. On the command line, wp wpmc status shows Configured as Yes or No.

When every field is filled in, the Upload Test row uploads a small test file and deletes it again. If it says “Test upload failed: …”, your storage refused the upload. The provider’s error follows the colon. See Connection test failing.

Check 3: Read the recorded error#

When an upload to storage fails, the file stays local and the error is saved.

  • Hover over Offload failed. Retry in the Media Library list view.
  • On the Dashboard, the Bulk Offload card shows “N items failed to offload”. Click it to see each file and its error.
  • Run wp wpmc failed to list them in the terminal.

After you fix the cause, click Retry all on the Dashboard, Retry on the row, or run wp wpmc offload --retry-failed.

ErrorWhat it meansHow to fix it
“Missing file: …” or “File not found: …”The file was not on disk when WP Media Cloud tried to upload it.Check that uploads are written to the server, then retry.
“HTTP 403 AccessDenied: Access Denied”The key cannot write to the bucket.Give the key write access to the bucket.
“HTTP 403 SignatureDoesNotMatch: …”The secret key is wrong.Paste the secret again in the setup wizard.
“Bunny Storage HTTP 401: …”The storage zone password is wrong.Paste the Zone Password again.
“No response from storage provider” or “cURL error 28: …”The server could not reach the provider in time.Ask your host to allow outbound HTTPS to the provider.
“Primary file could not be offloaded.”The main file failed, so the attachment was not recorded.Look at the other errors for the same file.

See Connection test failing for the full list of error codes.

Check 4: Is the file in the Media Library?#

Only Media Library attachments and their image sizes are offloaded. Files stored anywhere else stay on your server, for example:

  • theme and plugin images
  • plugin cache folders
  • BuddyBoss avatars and cover photos
  • form uploads that are not added to the Media Library

Image optimizers#

Image optimizers do not stop the upload. WP Media Cloud offloads the file as soon as it is uploaded. When a background optimizer finishes, the compressed file is offloaded again and replaces the original.

As a backup, WP Media Cloud also schedules a WP-Cron check 5 minutes after each upload. It offloads the file if it is still local. This backup needs WP-Cron to run.

See Image optimizers.

Multisite#

Each subsite has its own settings. A subsite you have not configured keeps its uploads local and shows Not configured. Set up each subsite in its own dashboard. Subsites can share one bucket when each uses the path prefix sites/%site_id%; otherwise give each its own bucket.

Debug log#

For more detail, turn on WP_DEBUG and WP_DEBUG_LOG in wp-config.php. WP Media Cloud then writes one line per upload to the debug log, wp-content/debug.log by default.

Lines look like [WPMC] post:123 skip:not_ready: ... or [WPMC] post:123 error:offload_failed: .... Turn debugging off again when you are done.

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