fraew Broken Media Inspector

Description

Broken Media Inspector is a fast, free media-maintenance tool for WordPress. It does two jobs exceptionally well — and unlike many alternatives, there is no paid tier, no row limit, and no external service.

🩺 Broken Media

After a migration, backup restore, or hosting change, images go missing. Broken Media Inspector scans every item in your Media Library and tells you:

• Which images are broken (file missing from disk, or incomplete metadata)
• Exactly which posts, pages, galleries and featured images use them — with direct edit links
• The likely cause and how to fix it

Missing files are grouped by folder, so a whole missing directory shows up as a single line instead of hundreds — the fastest way to spot a migration that dropped a folder. Results export to CSV.

The scan runs in two phases: a fast pass that checks every file on disk, then a background pass that works out usage only for the broken items. Thousands of images scan in seconds.

🧹 Orphaned Files

Over time your wp-content/uploads folder collects files that are no longer in the Media Library — leftovers from deleted posts, failed imports, and manual uploads. Broken Media Inspector finds them, shows you how much space they take, and lets you either:

• Add to Library — register the file so WordPress manages it again, or
• Archive — move it (with its folder structure preserved) to wp-content/uploads/fbmi-archive

Archiving is a safe, reversible cleanup. Nothing is deleted straight away: you archive the files you think you don’t need, check your site still looks right, and only then empty the archive. Changed your mind about a file? Restore it back to uploads in one click. This “archive, verify, then delete” workflow means you never lose a file you actually needed.

Generated thumbnails are recognised and never mistaken for orphans. Every file action is validated to stay inside your uploads folder and is limited to administrators.

Why choose this plugin

• Free and unlimited — no premium upgrade, no capped results
• Fast — two-phase scanning and in-memory usage matching
• Safe — the broken-media scan is read-only; file actions only touch what you select
• Self-contained — no external API calls, works on any host including shared hosting
• Zero configuration — install, activate, scan

Features

• Broken image detection — missing files and incomplete metadata
• Folder grouping — whole missing directories summarised in one line
• Usage mapping — featured images, Gutenberg blocks, galleries and direct URLs, with edit links
• CSV export — hand the report to a colleague or keep it on file
• Orphaned file scanner — find unregistered files in wp-content/uploads
• Safe archive workflow — archive orphans, verify your site, then delete or restore
• Import orphans — add unregistered files back into the Media Library
• Thumbnail-aware — generated sizes are never flagged as orphans
• Two-phase scanning — fast results even on large libraries
• No configuration, no external services, no paid tier

Usage

The plugin lives at Tools > Broken Media Inspector and has three tabs.

Broken Media

1. Click “Scan Media Library”.
2. A progress bar tracks the scan; results appear grouped by folder.
3. For each broken image you see the likely cause, a suggested fix, and direct edit links to every post/page/gallery that uses it.
4. Click “Export CSV” to save or share the full report.

Orphaned Files

1. Click “Scan Uploads Folder” to list files on disk that aren’t in the Media Library.
2. Select the files you want to act on (individually or with “Select all”).
3. Choose “Add to Library” (register them) or “Archive selected” (move them aside — nothing is deleted yet). A progress bar tracks large batches.

Archive

1. After archiving, check your site still looks and works correctly.
2. Open the Archive tab: “Restore” anything you still needed, or “Delete selected permanently” to reclaim the space once you’re sure.

Support

For support, documentation, and feature requests, visit:
https://thebigcity.co.nz

License

This plugin is released under the GPLv2 or later license. See license.txt for full details.

Credits

Broken Media Inspector is developed by Christopher Andrews.
https://thebigcity.co.nz

Built to help WordPress administrators diagnose broken media after migrations, backups and hosting changes — and safely clean up the stray files left behind. Free and unlimited. If it saves you time, you can support development at https://buymeacoffee.com/fraew ☕