Skip to main content

Troubleshooting

The service is not ready​

Check docker compose logs --tail=100 zorka, configuration and key readability for user 10001, license status on the admin listener, and required sources/storage. Resolve the cause before switching traffic.

In a licensed distribution, an expired lease stops new image responses until renewal succeeds. YAML does not provide a bypass.

A local image cannot be found​

Verify the mapping from UPLOAD_DIR to /mnt/upload, the profile name and the path relative to its root. Do not use symlinks. With the standard alias, /upload/products/a.jpg reads products/a.jpg inside the source root.

An HTTPS source is rejected​

Ensure the exact hostname is in allowed_hosts, its certificate is valid, and DNS plus every redirect point to public addresses. Allowing the initial hostname does not automatically allow a different redirect hostname.

URL parameters cause errors​

File routes support only the optional v parameter. Remove w, h, q and other parameters added by third-party loaders. Configure quality in the profile; dimensions are preserved.

File size did not improve​

Inspect the actual Content-Type and whether the original fallback was used. Compare the same source with the same settings; an already well-compressed original may not deliver the expected savings. Tune quality on a representative sample.

Expected cache hits are missing​

Check X-Image-Cache, lifetimes, entry-size limits and backend availability. Large images may not fit the fast cache. Reprocessing after expiration or source changes is expected.

Useful troubleshooting details​

  • Image version or digest and selected profile.
  • X-Request-ID, status and safe response headers.
  • A minimal source example without private data.
  • A configuration excerpt without credentials or keys.

Do not publish activation keys, registry passwords, tokens or source files containing personal data.