Troubleshooting
Every image that failed or was skipped has its reason in the report. Open the image’s row to read it.
Common messages
| Message | What it means | What to do |
|---|---|---|
| Service 401: unauthorized | The API key is missing or wrong. | Paste the key again in Settings, press Check now, then press Re-optimize on the affected images. |
| Service 415: unsupported_media_type | The file isn’t a JPEG, PNG, WebP or AVIF, for example a GIF. | Nothing. ImgCrisp leaves these files as they are. |
| Service 413: payload_too_large | The file is over 50 MB. | Make a smaller copy and upload that. |
| File missing on disk | WordPress has a record of the image but no file. | Upload the file. ImgCrisp looks for missing files again every few minutes, and Bulk Optimize has a Re-check button. |
| Backup failed; refusing to optimize without a restorable original | ImgCrisp couldn’t copy the original into the backup folder. | Check that wp-content/uploads is writable and has space. |
| Failed to write | ImgCrisp couldn’t save the optimized file. | Check that wp-content/uploads is writable and has space. |
| Transport error, Service 5xx or Malformed service response | The service or the network had a problem. | Usually nothing. ImgCrisp tries each image three times. |
| Verify: … | The Verify check found a problem with the files on disk. | Press Re-optimize on the image. |
When the service is busy, images wait 30 seconds and try again. That doesn’t count as a failed try, and you won’t see a message.
Bulk Optimize says Paused
After 10 failures in a row, ImgCrisp pauses the queue rather than keep failing. Check Service health on the same screen, fix what it shows, then press Resume.
The connection check
Service health on Settings and Bulk Optimize shows whether the site can reach the service (Connected or Unreachable) and whether your key is accepted (Valid or Invalid). Press Check now for a fresh check.
If it reads Unreachable, your host may be blocking outgoing connections. Ask them to allow connections to api.imgcrisp.com.
Sending us diagnostics
Instead of giving us access to your site, send a diagnostics file:
- In WordPress, go to ImgCrisp, then Settings, then Download diagnostics, or
- On the command line, run
wp imgcrisp diag --file=imgcrisp-diagnostics.json.
The file has your site address, WordPress, PHP and plugin versions, your ImgCrisp settings with the API key hidden, image counts, and the failed images with their messages. It never includes image files. Attach it when you write to us.
Tools, then Site Health, then Info also has an ImgCrisp section with a short summary that is safe to copy and paste.