Skip to main content
Domain Agents›Kubernetes Agent›Troubleshooting

Troubleshooting

Use these diagnostic checks and remediation playbooks to resolve cluster connectivity, MCP subprocess timeouts, Kubernetes RBAC errors, and database locking issues in TalkOps Kubernetes Agent (k8s-autopilot).

Quick health check​

Run these commands first to inspect container status, cluster reachability, and live agent logs:

# 1. Check container status
docker compose -f ~/.k8s-autopilot/docker-compose.yml ps

# 2. Verify Kubernetes API reachability from your host shell
kubectl cluster-info

# 3. Tail live agent engine logs
docker compose -f ~/.k8s-autopilot/docker-compose.yml logs -f --tail=100

# 4. Run the installer health check
curl -LsSf https://raw.githubusercontent.com/talkops-ai/k8s-autopilot/main/scripts/install.sh | bash -s -- --status

Cluster connectivity issues​

dial tcp 127.0.0.1:6443: connect: connection refused​

Cause: Your ~/.kube/config points to 127.0.0.1 or localhost. Inside the k8s-autopilot container, localhost resolves to the container's own loopback interface rather than your host machine.

Fix:

  • macOS / Windows (Docker Desktop): In ~/.kube/config, replace https://127.0.0.1:<port> with https://host.docker.internal:<port>.
  • Linux: Configure the agent service in docker-compose.yml with network_mode: "host".
  • Kind / Minikube: Attach the k8s-autopilot container to the kind or minikube Docker network and use the control-plane container IP.

Kubernetes configuration file not found at /root/.kube/config​

Cause: The host kubeconfig file is missing or not mounted into the container.

Fix: Verify ls -la ~/.kube/config exists on your host and confirm ~/.k8s-autopilot/docker-compose.yml includes the read-only volume mount:

~/.k8s-autopilot/docker-compose.yml
volumes:
  - ~/.kube/config:/root/.kube/config:ro

JIT MCP connection failed or Connection timeout after 30s​

Cause: An MCP server subprocess took longer than MCP_TIMEOUT_CONNECT to initialize (for example, while downloading packages on first run) or could not reach a remote HTTP endpoint.

Fix:

  1. Open Settings → Runtime Config and increase MCP_TIMEOUT_CONNECT to 120 and MCP_TIMEOUT to 60.
  2. If using remote HTTP MCP servers via MCP_SERVERS, verify both containers share the same Docker network.
  3. Enable LOG_LEVEL=DEBUG to inspect the subprocess stderr output.

Workflow & approval issues​

Approval required, but no Approval Card buttons appear​

Cause: A transient WebSocket disconnect interrupted the A2UI card payload, or you are interacting over a plain-text client.

Fix: Type APPROVE or PROCEED in uppercase directly in the chat input. The agent's fallback intent parser recognizes explicit text confirmation when A2UI buttons are unavailable.

Operator repeats validation retries without converging​

Cause: The model's attempted fix for a manifest or chart schema error introduced a secondary validation error.

Fix: k8s-autopilot caps automatic self-healing retries at 2 attempts per tool call before pausing. Reply in chat with explicit constraints (for example, "Use Bitnami Redis with architecture=standalone and skip Sentinel").

Kubernetes RBAC errors​

Forbidden: User cannot create/list resource​

Cause: The Kubernetes ServiceAccount used by k8s-autopilot lacks RBAC permissions for the target API group.

Fix: Bind the ServiceAccount to a ClusterRole (or namespace-scoped Role) with the required API groups:

k8s-autopilot-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: k8s-autopilot-operator-role
rules:
  - apiGroups: ["", "apps", "batch", "networking.k8s.io", "autoscaling", "policy"]
    resources: ["*"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["traefik.io", "argoproj.io", "monitoring.coreos.com", "opentelemetry.io"]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: k8s-autopilot-operator-binding
subjects:
  - kind: ServiceAccount
    name: k8s-autopilot
    namespace: default
roleRef:
  kind: ClusterRole
  name: k8s-autopilot-operator-role
  apiGroup: rbac.authorization.k8s.io

Helm reports Error: release: not found for an existing release​

Cause: Helm v3 stores release metadata inside Kubernetes Secrets in the release's namespace. If the ServiceAccount cannot get and list v1/Secret resources in that namespace, Helm cannot see the release.

Fix: Ensure secrets and configmaps in core API group "" are permitted by your RBAC policy.

Database & logging​

sqlite3.OperationalError: database is locked​

Cause: High concurrent write load against the local SQLite checkpoint file.

Fix: For multi-user or high-concurrency deployments, switch the checkpoint backend from SQLite to PostgreSQL in Settings → Runtime Config → Backend Storage or set POSTGRES_URI in .env:

CHECKPOINT_BACKEND=postgres
POSTGRES_URI=postgresql://user:pass@postgres:5432/k8s_autopilot

Enable structured debug logging​

To capture full JSON logs across all LangGraph nodes and MCP tool calls, update ~/.k8s-autopilot/.env and restart the stack:

LOG_LEVEL=DEBUG
LOG_MODE=json
docker compose -f ~/.k8s-autopilot/docker-compose.yml up -d
On this page