The storage triage post assumed one thing: that the Media Usage index matches the site as it is today. Most weeks that holds on its own. The weeks it doesn’t are the ones that matter most for storage: a content import, a domain move, a bulk search-replace, a new CDN. Those are exactly when people go looking for space to reclaim, and exactly when a stale index can tell the wrong story.
This post is about knowing which kind of week you’re in.
What keeps the index current on its own
After the first complete scan, Media Usage doesn’t rescan the whole site every time something changes. It reacts to the normal ways WordPress content gets edited:
- Saving a post queues a targeted rescan of that post.
- Changing post metadata queues a rescan of the source it belongs to.
- Editing a watched site option queues a rescan of that setting.
- Uploading or regenerating an image queues a rescan for that image.
Noisy metadata like _edit_lock is ignored, so an editor sitting on a page doesn’t generate a stream of pointless work. On top of the incrementals, a full reconciliation runs 30 days after each successful scan as a standing correction for anything an incremental pass missed.
For day-to-day editing, that is enough. You don’t need to think about the index at all.
The changes incrementals can’t see
Incremental rescans depend on WordPress telling the plugin that something changed. Some of the biggest content events don’t do that, or do it in a way the plugin deliberately ignores.
Imports. Incremental rescans are skipped while WP_IMPORTING is set. That’s on purpose: an import that saves thousands of posts would otherwise queue thousands of individual rescans in the middle of the import. The trade-off is that imported content isn’t in the index until a full scan picks it up.
Direct database edits. A search-replace run from the command line or a database tool writes rows directly. WordPress’s save hooks never fire, so there’s nothing for an incremental rescan to react to. If that search-replace changed image URLs, for a domain move or an HTTP-to-HTTPS switch, the index is still holding the old picture of where each image is referenced.
Changes outside the database. Moving uploads to an offload service, putting a CDN in front of media, or changing the uploads path doesn’t touch post content at all. The references in your content may now point at a different host, and the scanner only sees what’s in the database.
Restores and staging pushes. Restoring a backup or pushing a staging database over production replaces content wholesale. Whatever the index knew before may not describe the content that’s live now.
In all four cases the 30-day reconciliation will eventually catch up. “Eventually” isn’t good enough if you’re about to make cleanup decisions this afternoon.
Rebuild first, triage second
The rule is simple: after any of the changes above, run Build usage index before you look at No references found or the reclaimable-space estimate.
A rebuild is safe to start on a live site. Results are published generation by generation: the rebuild writes to a new generation while the dashboard and Media Library keep reading the last successful one, and the new generation is only promoted once the rebuild actually completes. Nobody sees a half-built index while it runs.
That also means the dashboard you see during a rebuild is the old answer. Wait for the rebuild to finish and promote before you triage. Starting a cleanup pass against the previous generation, right after an import, is how real content ends up looking unreferenced.
Scans are bounded on purpose. Workers yield after roughly 2.5 seconds or at 80% of the PHP memory limit, and batches are capped at 10 site settings, 25 content sources, or 100 images per pass. A large import can take a while to index on a shared host. That’s the cost of not stalling the site, and it’s a fixed margin, not a setting.
Read Needs review after a migration, not just the totals
Migrations tend to produce the content the scanner treats carefully: very large pages, builder data that grew during a redesign, layouts copied in from another site. When a source hits a safety limit, its images stay in Needs review instead of dropping to No references found, and the dashboard names the source, the reason, and the limit it hit.
After a big change, look at that list before anything else. A jump in Needs review is the index telling you coverage isn’t settled yet. Resolve those sources with the protected retry before you treat the reclaimable estimate as anything more than a lower bound.
Watch for numbers that move for the wrong reason
Two patterns are worth a second look after a migration.
No references found jumps right after a URL change. If image URLs were rewritten outside WordPress and the index hasn’t been rebuilt, or content now points at a host the scanner doesn’t recognize as your media, references can look like they disappeared. Rebuild first. If the jump survives a complete rebuild, spot-check a handful of the newly unreferenced images on the front end before trusting it.
Reclaimable space spikes on an offloaded site. The estimate is based on indexed file-size data for attachments with a complete, warning-free No references found classification. It isn’t a walk of what’s actually on disk or in a bucket. On offloaded media, the bytes you’d reclaim may not live on the server at all.
Protect before the migration, not after
If you know a move is coming, protect the images that live outside the scanner’s world while the index is still a good picture of the site: logos loaded by a child theme, assets used only in CSS, files pulled in by a mu-plugin or an external system. Protection keeps those images out of reclaimable totals and out of Media Usage Pro’s Cleanup Queue eligibility while the dust settles.
A short checklist for the next big change
- Before the change, protect known external or CSS-only keepers.
- Make the change: import, search-replace, media move, restore.
- Run Build usage index and wait for the new generation to promote.
- Work through Needs review and skipped sources until the dashboard is warning-free.
- Compare No references found and reclaimable space against what you saw before. Investigate any jump the change itself doesn’t explain.
- Only then go back to the triage workflow.
None of this deletes anything, and Pro’s Cleanup Queue still only accepts images from a complete, warning-free index with zero references. The point of rebuilding first is the same as everywhere else in Media Usage: a storage decision is only as good as the evidence underneath it.