Troubleshooting

The Dashboard surfaces every pipeline error as a short code (ip_blocked, transport_error, …) plus a one-line description. This page lists every code, the most likely cause, and how to fix it.

For "the proxy URL pattern doesn't reach PHP at all" problems, scroll down to Routing not working instead.

Error Codes

Security violations

Code	Description	Typical cause / fix
invalid_url	The source URL is malformed or unparseable.	The ASA2 placeholder data is bad — check the product in your repository.
invalid_scheme	The source URL uses a protocol other than http/https.	A data:, file:, or ftp: URL slipped in. Skip or fix the source.
origin_not_allowed	The source host is not on the origin allowlist.	Add the host to your origin allowlist once the editor ships.
dns_resolution_failed	The source host could not be resolved via DNS.	Server DNS or outbound firewall issue. Run dig <host> on the server to confirm.
ip_blocked	The resolved IP address is a private/loopback range (SSRF guard).	The origin actually sits behind NAT / on localhost. Don't proxy it — this is what the SSRF guard is for. See SSRF Protection.

Fetch failures

Code	Description	Typical cause / fix
transport_error	Network transport error contacting the source server.	Outbound firewall blocking the origin, TLS/cipher mismatch. Test with curl -v from the server.
http_error	The source server returned a non-success HTTP status.	Origin responded with 403 / 404 / 5xx. Open the URL in a browser to verify it still exists.
empty_body	The source server returned an empty body.	Origin misbehaving or hot-linking blocked. Retry; if it persists, contact the origin operator.
too_large	The source image exceeds the allowed maximum size.	The source is bigger than the configured cap. Switch to a smaller variant URL or raise the cap.

Driver failures

Code	Description	Typical cause / fix
unreadable	The fetched bytes are not a readable image.	The origin returned an HTML placeholder ("image unavailable") instead of an image. Inspect the URL.
unsupported_format	The image format is not supported by the active driver.	WebP/AVIF on a PHP build without GD WebP/AVIF support. Check gd_info() output.
decode_failed	Decoding the image failed inside the GD driver.	Corrupt source. Re-fetch in a browser; if it loads there, file a bug report.
encode_failed	Re-encoding the resized image failed inside the GD driver.	Out of memory. Increase PHP's memory_limit (256M is a reasonable baseline for high-resolution images).
internal	Internal driver error (memory or GD allocation).	Same — usually memory_limit. Check PHP error log for a Fatal error: Allowed memory size exhausted line.

Signed URL failures

These only appear when URL signing is enabled.

Code	Description	Typical cause / fix
signature_missing	A signed proxy URL was expected but no signature segment was present.	Almost always a stale-cache symptom — see signature_missing after upgrading or activating signing.
signature_invalid	The signed proxy URL signature did not verify.	The URL was edited (e.g. by a CDN URL rewriter), or the signing secret was rotated since the URL was generated.

signature_missing after upgrading or activating signing

If your Dashboard suddenly fills with signature_missing errors, the most common cause is the ASA2 template cache (or any page-level cache, e.g. WP Rocket / W3TC / LiteSpeed / Varnish / Cloudflare) holding HTML that was rendered before the proxy started producing signed URLs. The cached pages reference URLs without the /s/<sig>/ segment that the pipeline now requires.

This is also the expected symptom right after installing or updating the Image Proxy add-on on a site with a warm ASA2 template cache. The cached HTML still references unsigned proxy URLs that the new pipeline rejects. The fix is the same template-cache flush described below — no toggle or secret change is required to trigger it.

Resolution:

1. Flush the ASA2 template cache (ASA2 → Templates → Empty cache). From v1.0 onward, the proxy auto-flushes this cache on signing rotation and on activation changes — but a one-time manual flush is needed when upgrading from a pre-signing version.
2. If a page-cache plugin or CDN is in front of WordPress, flush that as well.
3. Do not flush the Image Proxy cache via Tools → Purge cache. It is keyed by source URL + dimensions, not by the signed proxy URL, so all cached image bytes remain valid. Flushing it would cause unnecessary re-fetches from the origin.
4. After flushing, watch the Recent errors panel for a few minutes. New signature_missing events should stop appearing.

Routing not working

If proxy URLs return 404 or images don't appear at all even though the master switch is on, the most likely cause is that the proxy URL pattern doesn't actually reach PHP. The canonical instrument for this is Tools → Routing check:

1. Open ASA2 → Image Proxy → Tools and run Routing check.
2. Look at the Permalink mode field:
   • Pretty permalinks — the proxy URL should reach PHP via WordPress rewrite rules. If the live response is not HTTP 200, your .htaccess (Apache) or try_files block (nginx) is likely not forwarding requests to index.php for unknown paths.
   • Plain permalinks — Fallback active should report Yes and the sample URL should include /index.php/. If you see No with Plain permalinks, the plugin is not detecting the permalink mode correctly; reload Settings → Permalinks and save.
3. If the live response shows a non-200 HTTP status, check the Hint and Recommendation fields for a concrete next step.

A green Routing works result combined with 404s on actual images usually means an upstream proxy (e.g. a CDN or reverse proxy) is rewriting or dropping the proxy URLs before they reach WordPress. Bypass the CDN and re-test against the origin directly to confirm.

Backend Fallback Warning

If the Dashboard shows a yellow fallback badge on the cache backend chip, the configured backend is unavailable and the pipeline is running with NullCache. Open Settings → Cache backend, confirm the backend is selected correctly, and resolve the underlying issue:

• Redis — install the phpredis PHP extension and restart PHP-FPM.
• Memcached — install the ext-memcached PHP extension and restart PHP-FPM.
• Filesystem — make sure the configured directory exists and is writable by the web server user.

See Cache Backends → Fallback Behaviour for details.