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 restricted-network installs).
• 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; 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; regenerate 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. Generate a fresh key and upgrade the release.

SBOM upload rejected for an org-scoped key

Uploads to /v1/sboms/upload/cyclonedx require a cluster-scoped key. If you created an organization-level key and gave it to the scanner, heartbeat-level auth may work while uploads are rejected. Create the key on the cluster itself in the dashboard — why uploads are cluster-scoped.

Helm install fails

• unsupported protocol scheme "oci" — your Helm is older than 3.8. Upgrade Helm, or use the classic repo method: helm repo add lockdep https://charts.lockdep.io.
• 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

• No pod starts since install — scanning is triggered by pods starting. On a very quiet cluster, restart a workload to trigger the first scan:
  bash

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

• Uploads deduplicated — images the platform has already seen (matched by content hash) are intentionally not 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