Docs

Images not loading after migration

6 min readUpdated November 9, 2026

Use these checks when images break after moving to WP Media Cloud from another offload plugin, or after moving the site.

Start here: look at the broken URL#

  1. Open the broken image in a new tab, or find its address and status code under Network in your browser’s developer tools.
  2. Go to Media Cloud > Health and click Run All Checks.
The image address points atStatusLikely causeSee
Your own domain404The file is not offloaded and its local copy is gone, or rewriting is offChecks 1 and 2
Your CDN or bucket404The key does not exist in the bucketChecks 4 and 5
Your CDN or bucket403Public reads are not allowedCheck 6
The old plugin’s CDN or bucketanyThe address is saved in your content, or a page cache is staleChecks 7 and 8
Your CDN, after running URL Replace on a version before 1.2.1404Links were switched for files that were never offloadedCheck 10

Check 1: Is every attachment offloaded?#

Health tab checks for URL rewriting and the CDN
  1. On the Dashboard, the Bulk Offload card shows how many of your media are offloaded and how many remain.
  2. If items remain, click Continue Offload or Offload All Media.
  3. If the card says some items failed to offload, open the list, read each error, fix the cause and click Retry all.

A file that is not offloaded loads from your server. If Remove local files was on, or the old plugin deleted local copies, it may be missing there (Check 9). If the run doesn’t finish, see Bulk offload stalled.

Check 2: Is Rewrite URLs on?#

Go to Media Cloud > Settings, find the Offload Behaviour card, switch on Rewrite URLs and click Save Settings. On the Health page, the URL Rewriting row says “URL rewriting is disabled in Settings.” when it is off.

Check 3: Is the storage connection working?#

On the Health page, check the Bucket, Upload Test and CDN URL rows. If one fails, see Connection test failing. Common causes after a migration are rotated keys, a renamed bucket, and a region that does not match the bucket’s location.

Check 4: Does the CDN URL serve the bucket?#

Each address is the CDN URL from Settings followed by the file’s key, for example https://cdn.example.com/2024/01/photo.jpg.

  1. Compare the CDN URL in your provider’s CDN card with the broken address.
  2. In your provider’s console, find the same key. The folders and file name must match exactly.
  3. If a CDN sits in front of the bucket, check its origin is this bucket.
  4. If you changed the CDN address, click Update all media URLs under Apply to Existing Media, then clear your page cache.

Check 5: Did the old plugin use a path prefix?#

This applies to imports from WP Offload Media, Media Cloud by ILAB and Advanced Media Offloader. Some of them store files under a prefix, such as wp-content/uploads/2024/01/photo.jpg.

WP Media Cloud 1.2.1 serves imported files from their exact keys, prefix included: in the Media Library, in srcset and in post content. If prefixed images still break, update the plugin, clear your page cache and check again.

To move imported files to plain keys such as 2024/01/photo.jpg anyway:

  1. Back up your database, and keep the old bucket contents until you have finished.
  2. Run wp wpmc restore to download the files to your server, or use Download All to Server on the Dashboard.
  3. Run wp wpmc clear-records to clear WP Media Cloud’s records. Nothing is deleted from storage.
  4. Run wp wpmc offload to upload the files again. They use your own Path prefix setting, or none.
  5. Clear your page cache and check the pages again.

Check 6: Can the public read the files?#

A 403 from the bucket or CDN means the files are not public. Your storage provider’s guide explains how to allow public reads for Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2, Google Cloud Storage, Hetzner Object Storage and S3-compatible storage.

Files that WP Offload Media kept private are imported as regular files and need public reads too. Protected store files (WooCommerce and Easy Digital Downloads product files) are the exception: they are served with signed links, see WooCommerce secure downloads.

Check 7: Is a page cache serving old HTML?#

Pages cached before the migration still contain the old image addresses. Clear your caching plugin, your host’s cache and any CDN full-page cache.

Check 8: Are old addresses saved in your content?#

URL Replace scan results

WP Media Cloud switches your own uploads address to the CDN as pages load, for files that are in your bucket. It matches every form that address is saved in: https://, http:// (for example on a site that moved to https), //, with or without www, and JSON-escaped. It does not change addresses on other hosts.

If your content links to the old plugin’s bucket or CDN, or to an old domain, those images break once that address stops serving the files. Some themes and page builders also save addresses in places other than post content.

  • Check the file is offloaded: in the Media Library, the WP Media Cloud field says Offloaded.
  • On a Kadence site, update to WP Media Cloud 1.2.1 or later; see Kadence.
  • To change saved addresses for good, use the URL Replace tool. Its preview lists every linked file, whether it can be switched and where it is used, which also shows files that never reached the bucket. Back up your database and try it on a staging copy first.

Check 9: Were local files removed before they were offloaded?#

If Remove local files was on before the bulk offload finished, or the old plugin deleted local copies, a file whose upload failed can be missing both on your server and in the bucket.

  1. Compare the Dashboard counts and open the failed list.
  2. In the URL Replace preview, files marked Missing or Recorded, but not found in the bucket are in neither place.
  3. Restore missing files from a backup into the same folder in wp-content/uploads.
  4. Click Retry all.

To remove local copies safely after a migration, leave Remove local files off until the offload finishes, then use Remove local copies. It confirms each file in the bucket before deleting its local copy.

Check 10: Broken images after running URL Replace (versions before 1.2.1)#

Before 1.2.1, URL Replace switched every uploads address to the CDN, including files that were not offloaded. Those now point at files that are not in the bucket. Run URL Replace again with CDN URLs back to local: it switches back each address whose local file exists. Then finish the offload and run Local URLs to CDN, which only switches files that are in the bucket.

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