Agent Not Appearing in Dashboard
Steps to diagnose when your deployed agent doesn't show up in KubeWatch.
If you've deployed the agent but it doesn't appear in the dashboard within 60 seconds, work through these checks in order.
Check 1: Is the API key correct?
Verify the KUBEWATCH_API_KEY environment variable is set to the exact key from Settings → API Keys. Even a single extra space or missing character will cause authentication to fail.
Docker:
docker inspect kubewatch-agent | grep -A5 KUBEWATCH_API_KEY
Kubernetes:
kubectl get pod -n kubewatch -l app=kubewatch-agent -o jsonpath='{.items[0].spec.containers[0].env}'
Check 2: Can the agent reach the gateway?
From the agent host, test connectivity to the gateway:
curl -v https://YOUR_KUBEWATCH_URL/health
Expected response: HTTP 200 with a JSON body. If this fails, there's a network or DNS issue, not a KubeWatch configuration problem.
For self-hosted installations:
curl -v https://your-domain.com/health
Check 3: Is outbound port 443 open?
The agent needs outbound TCP to port 443. On many servers, outbound traffic is allowed by default, but some environments have restrictive egress rules.
nc -zv YOUR_KUBEWATCH_URL 443
If this times out, contact your network administrator to allow outbound HTTPS from the agent host.
Check 4: Check agent logs
Docker:
docker logs kubewatch-agent
Kubernetes:
kubectl logs -n kubewatch -l app=kubewatch-agent --tail=50
Common error messages:
| Log message | Cause | Fix |
|---|---|---|
unauthorized | Wrong or revoked API key | Regenerate key in dashboard, update agent env var |
connection refused | Gateway not reachable | Check URL and port 443 access |
certificate verify failed | TLS issue on self-hosted with self-signed cert | Add KUBEWATCH_TLS_SKIP_VERIFY=true (dev only) |
no such file or directory: /var/run/docker.sock | Socket not mounted | Add the volume mount to your docker run / compose command |
Check 5: Is the Docker socket accessible?
The agent needs access to /var/run/docker.sock:
ls -la /var/run/docker.sock
Expected: a socket file owned by root with group docker:
srw-rw---- 1 root docker 0 Jun 16 10:00 /var/run/docker.sock
If the agent container is running as a non-root user without the docker group, it won't be able to read the socket. The simplest fix is to ensure the volume is mounted and the agent container runs with sufficient permissions.
Check 6: Is the agent already registered under a different name?
Check the dashboard agent list, look for an agent with a similar name or your server's hostname. It's possible the agent registered successfully but you're looking at the wrong organization or agent filter.
Still stuck?
Open a support ticket from Settings → Support and include:
- The output of
docker logs kubewatch-agent(last 100 lines) - The result of
curl -v https://YOUR_KUBEWATCH_URL/healthfrom the agent host - Your agent deployment method (docker run / compose / helm)