Start by classifying the broken image: the HTML may still reference the old domain, the correct URL may return 404 because the file was never copied, or the file may exist while the web server cannot read it. Those cases look similar in the browser but require different repairs.
Use the failing request to identify the layer
Inspect several broken images and record their requested URL, HTTP status and response. Then check whether each original file exists under the expected uploads path. A database search-and-replace cannot restore a missing file, and copying uploads cannot correct a stale URL stored in content.
Evidence to collect before changing paths
- Old and new site URL plus the exact image URL emitted in HTML.
- Physical file existence under the expected year/month directory.
- WordPress upload settings and the new document root.
- Owner, group and readable permissions on representative files and directories.
- CDN origin and HTTPS behaviour if media is served through an edge layer.
Four migration failures that need separate fixes
- Stored old URLs: content or metadata still contains the previous domain or subdirectory.
- Incomplete uploads copy: the database moved but some media files did not.
- Path mismatch: the new server expects uploads under a different document root or layout.
- Ownership/CDN failure: the file exists but the origin or web server cannot serve it correctly.
Repair URLs, files and permissions in that order
- Back up the database before any serialization-aware URL replacement.
- Re-copy missing uploads using file counts or checksums rather than guessing which folders are incomplete.
- Restore the documented owner/group and safe readable permissions instead of applying broad chmod changes.
- Purge CDN and thumbnail caches only after originals resolve correctly.
Migration routing or filesystem permissions?
If the migrated URL itself resolves incorrectly, compare with permalink 404s after a WordPress migration. If the file exists but PHP or the web server reports access errors, use ownership checks before changing chmod. These failures can coexist, so verify one representative original from disk to browser.
Do not regenerate thumbnails before originals are healthy
Thumbnail regeneration cannot recreate missing source files. It can instead consume disk and produce more derivative files while the actual migration remains incomplete.
How to verify the migration repair
Representative originals and resized variants should return 200, rendered HTML should use only the canonical domain and scheme, and a newly uploaded image should inherit the correct path, ownership and public URL without manual correction.
WP REPAIR INCIDENT STANDARD
Safe intervention sequence
A bulk search-replace helps only when stored URLs are wrong. It cannot copy missing files or repair filesystem ownership.
- Inspect several broken image requests and record URL, status and response body.
- Check whether each file exists under the expected uploads year/month path.
- Compare WordPress upload settings and the new document root.
- Verify owner, permissions, CDN origin and HTTPS scheme.
What must be verified
- Representative original and resized images return 200.
- Page source contains only the canonical domain and scheme.
- New uploads inherit correct paths and ownership.
Official technical sources
This guide explains the diagnosis. If the site is affected now, the intervention should preserve a rollback path and verify the real business journey.
See the emergency repair service →ABOUT THIS SYMPTOM
Frequently asked questions about this guide.
Will a database search-replace fix images that return a 404 after migration?+
Only if the URL stored in the database is wrong. A search-replace cannot copy files that never made it to the new server or fix filesystem permissions, so if the file itself is missing or unreadable, the URL will still point to something that isn't there.
Should thumbnails be regenerated before checking if the original images exist?+
No. Regenerating thumbnails first can consume disk space and create noise without fixing anything if the original files were never fully copied during migration — confirm the originals exist first.
Can images be missing even though the database migration was successful?+
Yes. The database and the media files are moved separately during a migration, so a fully correct database with updated URLs can still point to an uploads directory that is missing files if the copy was incomplete.
If files exist on the server but images still don't load, what else could it be?+
Check file ownership, permissions, and CDN configuration. A file can physically exist in the right uploads path yet still fail to load if the web server lacks read permission or the CDN origin and HTTPS scheme are misconfigured.