Troubleshooting
Diagnose common optimization, compatibility, queue, backup, and frontend delivery issues.
WebP is not generated
Check System Status. The server needs Imagick WEBP support or GD WebP functions. Also confirm WebP is enabled in Compression settings and the attachment is JPEG, PNG, or WebP.
AVIF is unavailable
AVIF depends on host libraries. Leave AVIF disabled if read or write support is missing. WebP and original images continue to work.
A visitor receives the original instead of WebP or AVIF
Check that a valid derivative exists for the matching responsive image size, frontend delivery is enabled, and the browser accepts the format. Vacuum falls back when a derivative is missing, corrupt, stale, too large, or not accepted. Configure page caches and CDNs to respect Vary: Accept or vary their cache key by Accept.
A derivative looks out of date
Replace or regenerate the source through WordPress so attachment metadata is refreshed. Vacuum checks the tracked source and output size, rejects stale registered files, and regenerates them during processing. Re-run the appropriate Media Library action or migration if a derivative is still missing.
Bulk queue stalls
Refresh queue status, pause and resume, then retry eligible failed jobs. An accepted retry returns the item to pending while it runs. Use Cancel Pending Work only to stop unstarted jobs safely, or Clear Failed after recording the reason. If failures continue, reduce server load, process fewer images at a time, and review PHP memory and execution-time values.
Images are skipped
Open the Media Library Vacuum column and read the skip reason. Common causes include SVG, animated GIF, excluded MIME type, size limits, filename patterns, missing files, or unsupported formats.
Restore is unavailable
Restore requires an existing, verified backup inside Vacuum's backup directory. If backups were disabled when an image was optimized, there may be no restorable copy for that attachment.
Frontend does not show WebP or AVIF
Confirm generated derivatives exist, frontend delivery is enabled, and the theme outputs images through WordPress functions. Hard-coded URLs may not pass through plugin filters.