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.

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.