Documentation menu

Common Errors

Error messages and how to resolve them.

Agent errors

failed to connect: transport: authentication handshake failed

The auth token is invalid or expired. Generate a new token from Clusters → Connect Cluster and update the Helm release:

helm upgrade dataagent oci://ghcr.io/data-agent-co/dataagent-chart \
  --namespace dataagent --reset-then-reuse-values \
  --set config.authToken=<new-token>

x509: certificate signed by unknown authority

The TLS CA certificate could not be fetched by the init container, or a custom CA is misconfigured. See Agent not connecting — TLS certificate issues.

ImagePullBackOff on agent pod

The image pull password is missing or wrong, or the cluster cannot reach ghcr.io.

  1. Copy the image pull password from the dashboard (Clusters → Connect Cluster — it is part of the install command). You do not need to create a GitHub token. Update the release with it:
helm upgrade dataagent oci://ghcr.io/data-agent-co/dataagent-chart \
  --namespace dataagent --reset-then-reuse-values \
  --set imageCredentials.password=<pull-password>
  1. Check that the cluster allows outbound TCP to ghcr.io:443. See Agent not connecting — Network / egress blocked for a check you can run.

ImagePullBackOff on a monitoring pod

prometheus-server, kube-state-metrics, and node-exporter pull public images from quay.io, registry.k8s.io, and docker.io. They do not use the image pull password, so changing it will not help. Allow outbound TCP 443 to those registries (the same egress check covers them), or reinstall with --set da-monitoring.enabled=false to skip the bundled monitoring.

Dashboard errors

“AI enrichment unavailable”

The organisation’s AI token budget has been exhausted. Enrichment resumes when the budget resets. See AI token budgets.

“Failed to load incidents”

A transient API error. Refresh the page. If the error persists, check the DataAgent status page or contact support.

“Cluster not found”

The cluster was removed from the organisation while you had its detail page open. Navigate back to the Clusters list.

Getting help

If none of the above resolves your issue, contact support with:

  • A description of the problem and when it started
  • Your organisation name and cluster name
  • Relevant pod logs (kubectl logs -n dataagent -l app.kubernetes.io/name=dataagent -c orchestrator --tail=100)
  • Any error messages from the dashboard

Cookie Settings