Skip to content
KAZCODE Universal Storage KAZCODE Universal Storage

Missing / Broken Files

Symptom

Media Library shows broken images (or a broken frontend image) after enabling Serve from S3.

Steps to diagnose

  1. Confirm Serve from S3 is actually on under Universal Storage → Settings.

  2. Check the attachment’s status in the Universal Storage → Media column — it should read offloaded. A status of pending or failed means the file may not actually be in your bucket yet.

  3. Open the delivery URL directly in a browser, outside of WordPress, to confirm it’s reachable on its own.

  4. Run a per-attachment check:

    Terminal window
    wp universal-storage verify --attachment-id=ID --verbose

Common causes

  • The bucket is private with no public-read path (no CDN, no public bucket policy) — configuring a storage profile does not make a bucket public by itself; see Public delivery on the relevant provider page.
  • The attachment genuinely failed to upload (status failed) and local deletion never should have been allowed to happen for it — if you believe this occurred, please check whether local storage policy was set to something other than “keep local files after a verified upload” (see Health & repair).
  • A generated image size was regenerated/edited (e.g. Image Editor, Regenerate Thumbnails) after the original offload, superseding the old object record.

Verify it’s fixed

wp universal-storage verify --attachment-id=ID --verbose reports the attachment as fully present, and the delivery URL loads directly in a browser.

Clearing a permanently-failed item

Universal Storage → Media → Failed items lists every attachment currently in a failed/partial state, with its recorded error and whether its local file is still present. Once you’ve fixed the underlying cause (credentials, bucket permissions, a missing local file), select the affected rows and use Clear selected to reset this plugin’s own tracking for them — it removes only the plugin’s own bookkeeping (status, last error, etc.), never the attachment or the local file, so a subsequent offload or retry starts completely fresh instead of carrying over a stale error. Use Ignore selected instead if you want to keep the item out of the Failed items list without resetting its history (e.g. a local file you know is intentionally gone forever).