Understanding the Media Library Scanner

Your WordPress media library drifts out of sync over time. You change themes and the old thumbnail sizes become dead weight while new sizes are missing. You enable WebP conversion but your existing 2,000 images don’t have WebP variants. You migrate hosts and some files don’t make the trip. WordPress doesn’t fix any of this on its own — it doesn’t even tell you about it. The Media Library Scanner finds every discrepancy between what your WordPress configuration expects and what actually exists on disk and in your cloud storage.

This post explains exactly what the scanner checks, how it works under the hood, what the fix operations do (and don’t do), and when you should run it.

---

What the Scanner Checks

The Media Library Scanner compares every registered attachment against your current WordPress configuration. For each image, it runs through several categories of checks. Here’s what each one means.

Corrupted Metadata

WordPress stores image metadata in the wp_postmeta table — dimensions, file sizes, the list of registered thumbnail sizes and their file paths. Sometimes this metadata gets corrupted: a migration tool drops fields, a database optimization plugin strips “unused” rows, or a crash during upload leaves incomplete records.

The scanner flags attachments where critical metadata fields are missing or malformed: no dimensions recorded, no filesize, or an empty sizes array when sizes should exist. Without this metadata, WordPress can’t serve the correct thumbnail for a given context and falls back to the full-size original — wasting bandwidth and hurting page load times.

Wrong Dimensions

Your theme and plugins register image sizes — thumbnail (150x150), medium (300x300), large (1024x1024), plus any custom sizes like hero-banner (1200x600). When an image is uploaded, WordPress generates thumbnails at each registered size.

But if you change size definitions after upload — say you change medium from 300x300 to 600x400 — WordPress doesn’t regenerate existing thumbnails. The old 300x300 files stay on disk and the metadata still references them. The scanner detects this mismatch: the thumbnail exists, but its dimensions don’t match what your current configuration expects.

Missing Sizes

Related to wrong dimensions, but different: the scanner checks for sizes that your WordPress configuration registers but that have no corresponding file on disk at all. This happens when you add a new image size to your theme (or switch to a theme that registers sizes your old theme didn’t) and your existing images were uploaded before that size existed.

WordPress only generates thumbnails at the sizes registered at the time of upload. If you add blog-card (400x300) to your theme six months after uploading 500 images, none of those 500 images will have a blog-card thumbnail. The scanner catches every one of them.

Deprecated Sizes

The opposite problem: your metadata lists sizes that your current theme no longer registers. You switched from a theme that used theme-hero-1200x600 to one that doesn’t. The files are still on disk, the metadata still references them, but nothing on your site actually uses them. They’re dead weight — consuming disk space and inflating your metadata.

The scanner flags these so you know they exist. The fix operation updates the metadata to remove references to deprecated sizes. The files themselves can be cleaned up separately via Orphan Detection if desired.

Missing WebP

If you’ve enabled WebP conversion in StaticQ’s settings, the scanner checks every image for corresponding .webp variants. Each thumbnail size should have a WebP version alongside the original JPEG or PNG.

This category lights up in two common scenarios: you enabled WebP after your library was already built, or you migrated from another optimization plugin that handled WebP differently (or didn’t generate WebP files at all).

Missing Files

The metadata says a file should exist at a specific path, but the file isn’t there. The database record is intact, the metadata lists the expected sizes and paths — but when the scanner looks on disk (or in the R2 bucket), the file is gone.

Common causes: files deleted manually via FTP, a migration that missed some directories, disk corruption, or a hosting provider that cleaned up “old” files. This is different from a missing size (where the size was never generated) — here, the file was generated at some point but has since disappeared.

Storage Sync Gaps

If you’re using R2 for cloud storage, the scanner checks that local files and cloud copies are in sync based on your storage mode:

• Local + Cloud mode: the scanner verifies that every file exists both locally and in R2. If a file is on disk but not in the bucket, or in the bucket but not on disk, it’s flagged.
• Cloud Only mode: the scanner verifies that every file exists in R2. Local copies may or may not exist (they’re removed after successful upload), but the cloud copy must be present.

This catches upload failures, partial migrations to cloud storage, and cases where files were manually deleted from R2.

---

How Scanning Works

The scan is a read-only operation. It examines files, reads metadata, and checks for the existence of expected resources. It does not modify, move, or delete anything. You can run a scan at any time without risk.

Scanning processes attachments in batches via AJAX requests from your browser. The default batch size is 100 attachments per request (configurable via SQ_SCAN_BATCH_SIZE in wp-config.php). Each batch loads the attachment metadata, checks the filesystem and cloud storage, and records any issues found. A progress bar shows how far through your library the scan has progressed.

For a library of 5,000 images, a full scan typically takes 2-5 minutes depending on your server speed and whether cloud storage checks are involved (R2 existence checks add a small amount of latency per file).

---

Understanding Scan Results

When the scan completes, results are grouped by issue category. Each category shows a count of affected attachments. You can expand any category to see the specific attachments and exactly what’s wrong with each one.

The per-attachment detail view shows:

• The attachment filename and ID
• Which sizes are affected
• What the expected state is vs. what was found
• The specific issue (wrong dimensions, missing file, not in R2, etc.)

This detail matters because not every issue requires the same urgency. Missing WebP variants for images that are already offloaded to R2 might be a low priority. Missing files for images that appear on your homepage are urgent.

---

Fixing Issues

You can fix issues in two ways: per-attachment (click the fix button next to an individual attachment) or in bulk (click Fix All to queue repairs for everything the scanner found).

Fix All queues the repair tasks through WordPress cron, just like normal image processing. They run in batches — the same SQ_CRON_BATCH_SIZE and SQ_CRON_MAX_SECONDS constants that control upload processing also control repair batches. This means repairs won’t spike your server’s CPU, even if the scanner found thousands of issues.

What the Fix Does

• Corrupted metadata: regenerates the metadata by reading the actual file on disk and rebuilding the sizes array
• Wrong dimensions: regenerates the thumbnail at the correct dimensions for your current configuration
• Missing sizes: generates the missing thumbnail from the original image
• Deprecated sizes: removes the deprecated size entries from the metadata
• Missing WebP: generates the WebP variant from the existing JPEG/PNG file
• Missing files: regenerates the file from the original image (if the original exists) or flags it as unrecoverable (if the original is also missing)
• Storage sync gaps: uploads the file to R2 (if missing from cloud) or downloads it from R2 (if missing locally, in Local + Cloud mode)

What the Fix Never Does

This is important: the fix operation has strict boundaries.

• Never deletes files — it only creates, regenerates, or uploads. Deprecated size entries are removed from metadata, but the actual files on disk are left untouched (Orphan Detection handles file cleanup separately).
• Never renames originals — your original uploaded file keeps its filename and path.
• Never modifies image content — it doesn’t re-compress, sharpen, crop differently, or alter the visual content of any image. Regenerated thumbnails use the same crop and resize logic WordPress uses during normal upload.
• Never touches post content — it doesn’t update URLs in your posts (that’s the Post Content Scanner’s job).

---

Overwrite Mode

By default, the fix operation skips files that already exist at the expected path with the expected dimensions. This is the safe behavior — it only fills in gaps.

But sometimes you want to regenerate files that already exist. Common reasons:

• You changed your JPEG compression quality setting and want all thumbnails re-generated at the new quality
• You switched from GD to Imagick (or vice versa) and want the different rendering engine applied to existing images
• You switched from local processing to Cloudflare Image Resizing and want the Cloudflare-generated versions to replace the locally-generated ones

For these cases, enable Overwrite mode before running the fix. This tells StaticQ to regenerate every file, even if one already exists at the correct dimensions. Use it deliberately — it will reprocess your entire library, which takes time and consumes processing resources.

---

Back Up Before Large Repairs

Before running Fix All on a large library, back up your database — specifically the wp_postmeta and wp_posts tables. The fix operation modifies postmeta records (updating sizes arrays, dimensions, and file references), and while it’s designed to be safe, having a backup lets you roll back if anything unexpected happens.

Most WordPress backup plugins can do a database-only backup in seconds. If you have WP-CLI access:

wp db export --tables=wp_postmeta,wp_posts backup-before-scan-fix.sql

This is a precaution, not an expectation of problems. But on a library with 10,000+ images, the fix operation will touch thousands of database rows, and a backup is cheap insurance.

---

When to Run the Scanner

The scanner isn’t something you need to run every day. It’s most useful at specific moments in your site’s lifecycle:

After changing themes. Your new theme almost certainly registers different image sizes than the old one. Existing images won’t have thumbnails for the new sizes, and they’ll have thumbnails for sizes that no longer exist. The scanner finds both problems.

After enabling WebP. If you turn on WebP conversion in StaticQ’s settings, your existing images don’t retroactively get WebP variants. Only new uploads go through the WebP pipeline automatically. The scanner flags every image that’s missing WebP, and Fix All generates them in bulk.

After changing registered image sizes. If you modify add_image_size() calls in your theme — changing dimensions, adding new sizes, removing old ones — existing images are stuck with the old sizes. The scanner detects the mismatch.

After a migration. Moving between hosts, changing domains, or restoring from a backup can leave gaps: files that exist in the database but not on disk, or files on disk that the database doesn’t know about. The scanner catches the database-vs-filesystem discrepancies.

After switching storage modes. If you change from Local + Cloud to Cloud Only (or vice versa), the scanner verifies that files exist where your new configuration expects them.

Periodically as a health check. Running the scanner every few months catches drift that accumulates from normal WordPress operations — plugin updates that change image handling, manual database edits, or hosting issues that silently corrupt files.

---

A Reliable Safety Net

The Media Library Scanner is the foundation of StaticQ’s maintenance toolkit. It’s the tool that ensures your media library matches your WordPress configuration — not the configuration from two themes ago, not the state after a botched migration, but right now. It’s read-only, safe to run anytime, and the fixes are controlled, specific, and reversible (with a database backup). Whether you’re managing one site or fifty, running the scanner after every significant change keeps your media library healthy and your images serving correctly.

Get StaticQ Media →