Skip to content
KAZCODE Universal Storage KAZCODE Universal Storage

Media Offload

New uploads (and every generated image size) move to your configured storage automatically, after WordPress finishes generating thumbnails — offload never races WordPress’s own image-generation step.

Before you begin

A tested storage profile and offload turned on under Universal Storage → Settings. If Cloudflare R2 is your target provider, the Cloudflare R2 WordPress media offload guide explains the end-to-end planning workflow before batch migration or local cleanup. For Amazon S3, use the complete WordPress S3 media offload guide. If you are choosing between the two providers, see Cloudflare R2 vs Amazon S3 for WordPress Media.

How it works

  • Theme and plugin static assets are never touched — only Media Library attachments.
  • _wp_attached_file always stays a relative path, never a URL. Existing remote objects resolve through the Storage Profile that owns their inventory row; changing the default upload profile affects new uploads, not historical media. Delivery/CDN changes on the owning profile apply when URLs are newly rendered.
  • A failed image size is never falsely marked offloaded — each file variant (original and every generated size) has its own tracked status.
  • If Serve from S3 is off, files still upload, but WordPress keeps serving local copies until you turn it on.

Verify it worked

Open Universal Storage → Media — the Media Library gets a status column showing offloaded, pending, failed, or missing per attachment, plus per-row offload, restore, and verify actions.

Troubleshooting

A specific attachment shows failed — check its error detail in Universal Storage → Media, or the dedicated failed-items panel there, which lets you filter, ignore, and export failures as CSV. Retry it individually, or run wp universal-storage retry_failed.

See also Local storage policies for how/when local copies get deleted after a successful offload.