Agent Skill · Okteto

okteto-debugging

Use when the user describes a broken or unhealthy Okteto environment. Triggers on phrases like: "service is crashing", "service keeps restarting", "service won't start", "environment is broken", "deployment is failing", "pods are stuck", "pods are not ready", "pods are pending", "CrashLoopBackOff", "OOMKilled", "ImagePullBackOff", "Evicted", "what's wrong with my service", "debug my environment", "why won't it start", "something's wrong", "logs show errors", "service isn't responding", "my code changes aren't showing up", "file sync is stuck". Also triggers if the user pastes kubectl or okteto output showing unhealthy pod states.

Provider: Okteto Path in repo: plugins/okteto/skills/okteto-debugging/SKILL.md

Skill body

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.

Step 3: Snapshot pod states

kubectl get pods -n "$ns"

This is the master triage signal. Map each pod to one of these states and apply the matching playbook below:

Pod state Playbook
CrashLoopBackOff Crash loop
OOMKilled OOM kill
ImagePullBackOff / ErrImagePull Image pull failure
Pending (> 60s) Unschedulable
Running but not serving / health checks failing Runtime error
No pods exist / deploy never completed Deploy failure
All pods Running and Ready Sync / dev mode issue

If the user named a specific service, filter to that service’s pods only. If no service was named, check all pods.


Playbooks

Crash loop (CrashLoopBackOff)

The container starts, crashes, and Kubernetes keeps restarting it.

# Get logs from the previous (crashed) container instance
kubectl logs <pod-name> --previous -n "$ns"

# If that fails (first crash, no previous), get current logs
kubectl logs <pod-name> -n "$ns"

# Check exit code and liveness/readiness probe config
kubectl describe pod <pod-name> -n "$ns"

Look for:

Common root causes:


OOM kill (OOMKilled)

The container exceeded its memory limit and was killed by Kubernetes.

kubectl describe pod <pod-name> -n "$ns"

Look for:

Fix pattern: Increase the memory limit in the service’s Helm values or okteto.yaml. Show the user the exact current limit and suggest a reasonable increase (typically 2×). Do not suggest removing limits entirely.


Image pull failure

Kubernetes can’t pull the container image.

kubectl describe pod <pod-name> -n "$ns"

Look for:

Common root causes:

Fix pattern: If the image should have been built by Okteto, run okteto build <service>. If the image is external, verify the tag exists. If credentials are the issue, help the user create an image pull secret.


Pending / unschedulable

The pod has been accepted by Kubernetes but hasn’t been scheduled onto a node.

kubectl describe pod <pod-name> -n "$ns"

# Also check recent namespace events for quota / resource pressure
kubectl get events -n "$ns" --sort-by=.lastTimestamp | tail -20

Look for in kubectl describe pod → Events:

Fix pattern: Match the error to the constraint. For resource requests, lower the request or ask the user to scale the node pool. For taints/selectors, show the current constraint and suggest removing or correcting it.


Runtime error (Running but unhealthy)

Pods are Running but the service isn’t responding, health checks are failing, or the user sees errors in requests.

# Get recent application logs
okteto logs <service> --since 10m -n "$ns"

# If that's not enough context
okteto logs <service> --tail 200 -n "$ns"

Look for:

Fix pattern: Quote the most relevant 5–10 lines of the stack trace or error. Identify the source file if named. Suggest the specific fix — a code change, a missing env var, or a dependent service that needs to be started.


Deploy failure

The pods never appeared — okteto deploy failed before creating them.

# Check if the manifest is valid first
okteto validate

# Check deploy logs if validate passes
okteto logs --deploy -n "$ns"

Look for:

Fix pattern: If okteto validate catches it, show the exact error and line. If it’s a Helm error, show the template path. If it’s a build error, show the Dockerfile stage that failed.


Sync / dev mode issue

All pods are Running and Ready, but the developer’s code changes aren’t being reflected in the dev container.

okteto status reports the file-synchronization state of the active dev container. It only works while an okteto up <service> session is running — if there isn’t one, there is nothing syncing; tell the user to start it.

okteto status -n "$ns"

# If the summary isn't enough, get syncthing troubleshooting links
okteto status --info -n "$ns"

Look for:

The richest signal is the okteto up terminal itself — sync errors and conflict warnings surface there first, and you cannot see that session. Ask the user to paste its output.

Fix pattern: Check the sync paths in okteto.yaml against the actual directory structure. If paths are correct, try okteto down followed by okteto up <service> (the user must run okteto up interactively — never run it yourself). If sync is stuck, okteto doctor will generate a diagnostic bundle.


Output format

Always emit one block per unhealthy service:

## Diagnosis: <service-name>
**Root cause:** <one sentence>
**Evidence:**
<relevant excerpt from logs or describe output — 5 to 20 lines, no more>
**Fix:**
<exact command to run or code change to make>
**Confidence:** High / Medium / Low

Use Low confidence when:

If all pods are healthy, report:

All services are Running and Ready. No obvious failures detected.

If you're still seeing issues, run `okteto doctor` to generate a full diagnostic bundle.

Common gotchas

Skill frontmatter

license: Apache-2.0

Work with this as data

Every skill here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for agent skills

4 MCP tools reach this
  • find_skillsBrowse and filter every skill in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This skill
curl "https://apis.io/api/v1/skills/okteto-debugging"
All agent skills
curl "https://apis.io/api/v1/skills?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.