okteto-debugging

Okteto Environment Debugger

This skill triages broken Okteto environments. When a service is misbehaving, run through the triage algorithm below, apply the matching playbook, and emit a structured diagnosis. Do not guess — always let the command output drive the conclusion.

Diagnostics are read-only: kubectl get, kubectl describe, kubectl logs, and kubectl get events are fine here. Never mutate the cluster with raw kubectl/helm — fixes go through okteto build and okteto deploy (see the okteto skill for lifecycle operations, worktree isolation, and teardown rules).

Triage algorithm

Run these steps in order. Stop at the first step that identifies the failure.

Step 1: Verify connectivity and pin the namespace

okteto context show

If this fails, the user is disconnected from the cluster. Stop and help them reconnect (okteto context use <url>) before proceeding.

The JSON output includes the active namespace. Capture it — every command below targets it explicitly as $ns:

ns=$(okteto context show | jq -r .namespace)

If you are working in an isolated worktree namespace (see the okteto skill), use that namespace instead — the environment you need to debug lives there, not in the context's default.

kubectl must target the same cluster and namespace as Okteto. kubectl reads its own kubeconfig, which can point at a different namespace — or a different cluster entirely — than the Okteto context, especially when multiple agents or worktrees are active on the same machine. Run okteto kubeconfig to download credentials for the cluster selected via okteto context, and pass -n "$ns" on every kubectl command. If kubectl get pods -n "$ns" errors or shows pods that don't match the services in okteto.yaml, fix the kubeconfig before trusting any diagnostic output.

Step 2: Discover services

cat okteto.yaml

Parse the deploy and dev sections for canonical service names. Never hardcode service names — always derive them from okteto.yaml.