• The token is missing, malformed, or was revoked. Check that PIXEL_EAGLE_TOKEN is set in the environment of the step that runs the CLI; in GitHub Actions, secrets are not available to workflows triggered from forks.
• Tokens are scoped to a single project: a valid token used against a run of another project is rejected.
• Run and comparison IDs from a different project also return 401 rather than 404, so double-check the IDs.

• Monthly comparison quota exceeded (or the screenshot equivalent): the space is over its monthly quota. Check the Usage page in your space settings.
• Subscription required: the request uses a paid feature (ꟻLIP, non-zero tolerance or dilation, webhooks) on a space without an active subscription.

Comparisons are processed asynchronously: triggering one returns immediately and the diffs are computed in a queue. Poll the corresponding GET endpoint until every screenshot's difference is done, or use pixeleagle compare-run ... --wait, which polls for you (default timeout 300s, configurable with --wait-timeout).

On busy periods a comparison can stay queued for a little while; if it stays stuck for a long time, re-triggering the same comparison is safe.

• If the two screenshots have different dimensions, both are resized to the smallest common size before comparing, which typically inflates the difference score. Make sure your test environment produces screenshots at a fixed resolution (watch out for OS scaling and HiDPI).
• Anti-aliasing and GPU/driver differences cause per-pixel noise. Consider a small tolerance, a threshold, or the ꟻLIP evaluator, and use the Evaluate view to dial in values.
• Comparing runs from different platforms? Use --same platform style metadata matching so runs are only compared against runs from the same environment.

Screenshots are matched between runs by name. A renamed screenshot appears as one missing plus one new entry. Keep names stable across runs: with the CLI, --clean-name uses the file name without its extension, so make sure your test suite writes files with deterministic names (no timestamps or random suffixes).

compare-run --filter key:value selects the latest earlier run whose metadata matches every filter. If no run matches (first run on a project, a typo in the key, or metadata not set when the run was created), there is nothing to compare against. Check the metadata of past runs in the UI, and see auto comparison by metadata for the <same> semantics.

• Webhooks require an active subscription and a URL starting with http:// or https://.
• Deliveries time out after 10 seconds and are retried up to 3 times only on connection errors, 5xx, and 429. A 4xx from your endpoint is treated as permanent. Respond with a 2xx quickly and process asynchronously.
• If signature verification fails, make sure you compute the HMAC over the raw request body, before any JSON parsing. See Webhooks.

install.sh supports Linux and macOS on x86_64 and aarch64. On Windows, or for other platforms, download a binary from the GitHub releases or build from source with cargo install --git https://github.com/vleue/PixelEagle-cli --features cli.