Troubleshoot the Kubernetes Agent

Use this guide when the Kubernetes Agent cannot register, connect, remain online, or access the expected cluster resources.

Agent remains in Waiting

Possible causes:

• the installation command was not executed;
• the registration token expired;
• the token was already consumed;
• the cluster identifier does not match;
• the agent cannot reach IncidentFlow.

Check the agent pod status and recent logs. If the registration token expired or was consumed before registration completed, create a new agent registration and use a new token.

Agent pod does not start

kubectl get pods \
  --namespace incidentflow-agent

kubectl describe pod \
  --namespace incidentflow-agent \
  <pod-name>

Look for image pull failures, missing Secrets, invalid Helm values, scheduling failures, insufficient CPU or memory, or admission policy failures.

Authentication or registration fails

Confirm that:

• the token was copied completely;
• the token is less than 24 hours old;
• the token has not already been used;
• the agent is connecting to the correct IncidentFlow environment;
• the platform and gateway URLs are correct.

Agent is offline

Check recent logs and outbound connectivity to the IncidentFlow platform API and agent gateway. Common causes include DNS resolution failure, blocked HTTPS traffic, blocked secure WebSocket traffic, proxy configuration errors, expired or revoked agent credentials, or an unavailable agent gateway.

Kubernetes permission denied

The agent uses read-only Kubernetes permissions. Verify its effective access:

kubectl auth can-i list pods \
  --as system:serviceaccount:incidentflow-agent:incidentflow-k8s-agent \
  --all-namespaces

Repeat the check for namespaces, deployments, services, events, and pod logs as required by your configuration.

Agent is connected but MCP returns no resources

Verify:

• the MCP request resolves to the correct workspace;
• the selected cluster is correct;
• namespace restrictions include the expected namespace;
• the agent heartbeat is recent;
• the requested resource exists;
• the ServiceAccount has the required read permission.

Use k8s_agent_status, k8s_connection_health, and k8s_rbac_check to narrow down the problem.

Collect diagnostic information

When contacting support, include the cluster identifier, agent version, installation method, Kubernetes version, namespace, pod status, sanitized recent logs, the MCP request_id, and the approximate time of the failure.