Common Errors
Error codes, their causes, and how to fix them.
This page documents the most common error responses from the KubeWatch API and how to resolve them.
HTTP error reference
| Error message | HTTP status | Cause | Fix |
|---|---|---|---|
unauthorized | 401 | Missing Authorization header or X-API-Key, expired JWT, or revoked API key | Re-authenticate to get a new JWT, or check your API key in Settings → API Keys |
invalid token | 401 | JWT is malformed, has an invalid signature, or has expired | Re-authenticate. If the error persists, verify JWT_SECRET is consistent across services (self-hosted) |
missing org_id claim | 401 | JWT was issued without an org_id claim (corrupted or from an old version) | Re-authenticate. Contact support if this persists after re-login |
org_suspended | 402 | Your organization's billing is suspended (failed payment) | Update your payment method in Settings → Billing |
rate_limit_exceeded | 429 | Too many API requests per second for your plan | Reduce request rate, add backoff/retry logic, or upgrade your plan |
upstream unavailable | 502 | A backend microservice is down or unreachable | Check gateway /health endpoint; self-hosted users check docker compose ps |
{"error":"unauthorized"} (from agent) | 401 | Agent's API key is wrong or has been revoked | Regenerate key in the dashboard and update KUBEWATCH_API_KEY on the agent |
org_not_found | 404 | The organization associated with the API key no longer exists | The organization may have been deleted; contact support |
agent_limit_reached | 403 | You've hit the maximum agent count for your plan | Delete unused agents or upgrade your plan |
Self-hosted specific errors
| Symptom | Cause | Fix |
|---|---|---|
| All services return 502 | Gateway can't reach backend services | Run docker compose ps and check which services are Up vs Exit |
| Login fails with 500 | Auth service can't reach the database | Check docker compose logs auth for DB connection errors; verify DATABASE_URL in .env |
| Metrics not saving | Ingestion service crashed | Check docker compose logs ingestion; often a DB schema migration issue on first startup |
| Dashboard shows blank page | NEXT_PUBLIC_API_URL points to wrong address | Update .env and restart the dashboard service |
| TLS certificate errors | Let's Encrypt cert not issued or expired | Check docker compose logs nginx; verify DNS points to your server |
Agent errors
| Log message | Cause | Fix |
|---|---|---|
failed to connect: dial tcp: connection refused | Gateway URL is wrong or gateway is down | Verify KUBEWATCH_SERVER_URL and check gateway health |
permission denied: /var/run/docker.sock | Agent doesn't have Docker socket access | Mount the socket and ensure correct permissions (see No Metrics Showing) |
push failed: 429 Too Many Requests | Pushing too frequently | Increase KUBEWATCH_INTERVAL (default is 15s; try 30s) |
certificate signed by unknown authority | Self-hosted with self-signed cert | Set KUBEWATCH_TLS_SKIP_VERIFY=true (development only) or install a valid cert |
agent_limit_reached | Organization at agent limit | Delete unused agents from the dashboard or upgrade the plan |
Getting more help
If you can't find the answer here:
- Check the GitHub Discussions for community answers
- Open a support ticket from Settings → Support in the dashboard
- Email support@kubewatchlabs.com
When contacting support, include:
- Your agent version (
docker inspect kubewatch-agent | grep Image) - Relevant log output
- The full error message including HTTP status code