Troubleshooting

Start here: what is the scanner saying?

Almost every issue is visible in the scanner's own logs:

kubectl get pods --namespace stackradar
kubectl logs --namespace stackradar <scanner-pod-name>

Cluster never shows as connected

The dashboard marks a cluster connected when it receives a heartbeat. If that never happens:

• Pod not running — kubectl get pods -n stackradar. An ImagePullBackOff in a private-registry environment means the image isn't mirrored or the pull secret is missing (see private registries & restricted networks).
• No egress — the scanner must reach https://api.stackradar.io. Test from inside the cluster:
  bash

  kubectl run egress-test --rm -it --restart=Never \
      --image=curlimages/curl -- \
      curl -s -o /dev/null -w "%{http_code}\n" https://api.stackradar.io/v1/heartbeat

  Any HTTP status code (even 401 or 404) proves connectivity is fine — the route only answers the scanner's POSTs, so an error status is exactly what a plain GET should get back; a timeout points at NAT/firewall/NetworkPolicy configuration — the per-platform notes for EKS, GKE, and AKS cover the usual culprits.
• Wrong credentials — 401 Unauthorized in the scanner logs means the API key is mistyped or revoked; rotate it in the dashboard and helm upgrade --set stackradar.apiKey=… (see key rotation).

401 Unauthorized

The X-API-Key header is missing, mistyped, or the key was revoked. Common causes: the key was pasted with surrounding whitespace or quotes into a values file, or an old key is still configured after a rotation. Rotate the key in the dashboard and upgrade the release.

403 Forbidden in the scanner logs

Every scanner endpoint — heartbeat, inventory, and SBOM check/upload — requires a cluster-scoped key, so a key that isn't bound to a cluster is rejected across the board. The other cause is a mismatch: the stackradar.clusterId the chart was installed with doesn't match the cluster the key belongs to (the error message says so explicitly). Only the heartbeat compares the two — the other endpoints derive the cluster from the key alone — but the heartbeat is the first thing the scanner sends, so a mismatch still surfaces within moments of install. Copy both values from the same cluster in the dashboard — see API keys & cluster scoping.

Helm install fails

• unsupported protocol scheme "oci" — your Helm is older than 3.8, the floor for OCI charts. Upgrade Helm (3.8+ or Helm 4).
• namespaces "stackradar" not found — add --create-namespace to the install command.
• cannot re-use a name that is still in use — a previous release exists. Use helm upgrade --install, or remove the old release with helm uninstall stackradar-scanner -n stackradar first.

Cluster is connected but no SBOMs appear

Start with the Coverage card on the cluster's Overview tab: it lists exactly which discovered workloads have no SBOM yet and how long each has been waiting. Anything waiting more than 30 minutes is flagged with the likely causes — usually private-registry authentication (the scanner pulls images itself and can't use node credentials; see private registries & restricted networks) or a scan failure worth checking the scanner logs for.

• No pod starts since install — the first full sweep covers what's already running, and after that scanning is triggered by pods starting. If a specific workload is missing, restart it to trigger a scan:
  bash

  kubectl rollout restart deployment <name> -n <namespace>

• Scans deduplicated — images this cluster has already scanned (matched by image digest) are intentionally not re-scanned or re-uploaded. Existing SBOMs still get new vulnerability matches as the advisory database updates.
• Upload errors in logs — schema-validation failures on upload produce a 400 with the failing paths listed. This should not happen with the scanner itself; if you're uploading CycloneDX from your own tooling, check the document is valid 1.6 JSON (see the format reference).

Dashboard says the scanner version is outdated

The agent reports its version with every heartbeat (the X-Scanner-Version header). To upgrade to the latest chart and image:

helm upgrade stackradar-scanner \
    oci://ghcr.io/lockdep/charts/stackradar-scanner \
    --namespace stackradar --reuse-values