clair-scanner "could not analyze / connection refused" to Clair server in CI

By Daniel Zoghalchali·Latchkey

clair-scanner needs two working connections: the CLI to the Clair server API, and the Clair server back to the runner to fetch image layers over the --ip you provide. If either is wrong, the scan aborts with a connection or "could not analyze" error before any CVE result.

What this error means

clair-scanner fails with "could not analyze layers" or a connection-refused error against the Clair API, or Clair times out fetching layers from the runner IP.

2026/06/30 11:02:41 [CRITICAL] Could not analyze layers:
Post "http://clair:6060/v1/layers": dial tcp 10.0.0.5:6060: connect: connection refused

Common causes

The Clair server is not up or not reachable

The service container had not finished starting, or the hostname/port the CLI uses does not resolve to it, so the API call is refused.

The wrong --ip prevents Clair pulling layers

Clair fetches layers back from the runner over --ip. A loopback or wrong address means Clair cannot reach the runner to analyze the image.

How to fix it

Wait for Clair and use the routable runner IP

1. Start Clair as a service and wait until its API responds.
2. Pass the runner IP that the Clair container can reach (not 127.0.0.1).
3. Point --clair at the service hostname and port.

IP=$(hostname -I | awk '{print $1}')
clair-scanner --ip="$IP" --clair="http://clair:6060" myimage:latest

Gate the scan on a healthy Clair

Poll the Clair health endpoint before scanning so the CLI does not run before the server is ready.

until curl -sf http://clair:6060/health; do sleep 2; done
clair-scanner --ip="$IP" --clair="http://clair:6060" myimage:latest

How to prevent it

• Wait for the Clair API to be healthy before scanning.
• Pass a runner IP that the Clair container can route to.
• Use service hostnames, not localhost, between containers.

Frequently asked questions

Related guides

References

• GitHub Actions documentation