Troubleshoot image optimization

Start with one attachment and distinguish upload, optimization, metadata, and delivery problems. A missing WebP response is not necessarily an optimization failure if the companion exists but the web server never selects it.

The upload finishes but no savings appear

Check that:

• the attachment is JPEG, PNG, GIF, AVIF, or WebP;
• the module was enabled before metadata was generated;
• the source file is readable and its directory writable;
• Imagick or GD can decode the source;
• the image and optimizer dependencies are present;
• the attachment was not already marked as optimized.

Use Media → Image optimizer → Optimize all images only after confirming that reprocessing the source is acceptable.

An attachment reports an error

The module treats processing as optional post-processing. If source optimization fails, it leaves the source file and its metadata unchanged. If the source succeeds but a later WebP conversion fails, the validated source remains optimized with matching metadata, and any previous WebP companion is kept. Correct the reported filesystem, image-driver, malformed-image, or optimizer problem, then retry with Optimize missing images.

Confirm the main file is readable before retrying. If the file is empty or corrupt, restore it from backup first.

Expected sizes are missing

Image Optimizer intentionally removes medium_large, 1536x1536, and 2048x2048 from the generated-size list. It also removes obsolete variants associated with the attachment after regeneration.

For any other missing size:

1. confirm the theme or plugin registers it before attachment metadata is generated;
2. inspect the image dimensions—WordPress does not create an enlarged derivative;
3. regenerate the test attachment;
4. verify its metadata and files agree.

WebP exists but visitors receive JPEG or PNG

Image Optimizer does not perform content negotiation. Inspect the CDN or web-server rule, response Content-Type, cache key, Accept handling, and original-format fallback.

The bulk page stops

Keep the page open, correct the first reported attachment problem, and rerun Optimize missing images. Completed attachments retain their marker; incomplete ones remain eligible. If a proxy or security layer blocks administration AJAX requests, allow the normal authenticated WordPress administration flow rather than exposing the operation publicly.