Skip to main content

Troubleshooting Guide

Diagnose and resolve issues with the Kubernetes Agent, MCP Server, and Helm workflows.

🔌 1. Connectivity & Startup​

"Config not found"​

Error: Kubernetes configuration file not found at /root/.kube/config Cause: The agent container cannot see your kubeconfig file. Fix: Ensure your Docker volume mount is correct.

# Correct mount syntax
-v ~/.kube/config:/root/.kube/config

"Connection Refused (MCP)"​

Error: Failed to connect to MCP server at http://localhost:9000 or Connection refused Cause: The main agent container cannot talk to the helm-mcp-server container. Fix:

  1. Docker Compose: Ensure both services are in the same network (default behavior).
  2. DNS: Use the service name helm-mcp-server instead of localhost in configuration if running manually.

"Connection Refused (Kubernetes)"​

Error: dial tcp 127.0.0.1:6443: connect: connection refused Cause: Your kubeconfig points to localhost. Inside Docker, localhost is the container, not your laptop. Fix:

  • Docker Desktop: Ensure context is set to docker-desktop.
  • Linux: Use --network host mode.
  • Generic: Replace localhost in kubeconfig with host.docker.internal (Docker Desktop) or your machine's LAN IP.

🛑 2. Workflow & Logic Issues​

Agent is Stuck "Thinking" or "Validating"​

Symptom: The agent enters a loop of "Validating..." -> "Fixing..." -> "Validating...". Cause: The Generator Agent is caught in a self-healing loop where its "fix" causes a new error. Fix:

  1. Wait: The loop has a hard limit (default: 2 retries per tool). It will eventually stop and ask_human for help.
  2. Interrupt: You can manually stop the agent and provide the correct file content via the prompt.

"Approval Required" but no Buttons​

Symptom: The agent says it needs approval, but the UI doesn't show buttons. Cause: The UI might not have rendered the A2UI card correctly, or you are using a CLI that doesn't support interactive elements. Fix: Type explicit text approval: "APPROVE", "YES", or "Proceed". The agent's text parser often acts as a fallback for UI buttons.

🔒 3. Permissions (RBAC)​

"Forbidden" on Deployment​

Error: deployments.apps is forbidden: User "system:serviceaccount:..." cannot create Cause: The agent's Service Account lacks the create verb for that resource. Fix: Update the ClusterRole bound to the agent.

# Grant full access to apps API group
- apiGroups: ["apps"]
  resources: ["deployments", "statefulsets"]
  verbs: ["*"]

Helm "Release Not Found" (but it exists)​

Error: Error: release: "my-app" not found Cause: Helm uses Secrets/ConfigMaps to store state. If the agent lacks permission to read Secrets in the target namespace, it cannot see the release. Fix: Ensure the RBAC role includes secrets access in the namespace where the chart is installed.

🐛 4. Low-Level Debugging​

Enable Debug Logs​

Increase verbosity to see the raw tool calls and MCP payloads.

Environment Variable:

LOG_LEVEL=DEBUG

Output:

[DEBUG] Calling tool: helm_mcp_server.list_releases
[DEBUG] MCP Payload: {"namespace": "default"}
[DEBUG] Tool Output: [...]

Inspect Generated Artifacts​

If the Generator fails, inspecting the raw files helps.

  1. Check the WORKSPACE_DIR (default /tmp/helm-charts inside container).
  2. If you mounted a volume, check your local mapped folder.
ls -F my-local-charts/my-app/templates/
cat my-local-charts/my-app/values.yaml