okteto-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Okteto Environment Debugger

Okteto环境调试器

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).

此技能用于诊断故障的Okteto环境。当服务运行异常时，请按照以下诊断流程执行，应用匹配的处理手册，并输出结构化诊断结果。请勿猜测——始终以命令输出作为结论依据。

诊断为只读操作：允许使用

kubectl get

、

kubectl describe

、

kubectl logs

和

kubectl get events

命令。禁止使用原生

kubectl

helm

修改集群——修复操作需通过

okteto build

和

okteto deploy

完成（生命周期操作、工作树隔离和销毁规则请参考

okteto

技能）。

Triage algorithm

诊断流程

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

按顺序执行以下步骤，在第一个识别出故障的步骤处停止。

Step 1: Verify connectivity and pin the namespace

步骤1：验证连接并锁定命名空间

bash

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

bash

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.

bash

okteto context show

如果此命令失败，说明用户已与集群断开连接。停止后续操作，先帮助用户重新连接（

okteto context use <url>

）。

JSON输出包含当前激活的

namespace

。请记录该值——以下所有命令均需显式指定此命名空间为

$ns

：

bash

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

如果您正在隔离工作树命名空间中操作（参考

okteto

技能），请使用该命名空间——需要调试的环境位于此命名空间，而非上下文默认命名空间。

kubectl必须与Okteto指向相同的集群和命名空间。 kubectl读取自身的kubeconfig，其指向的命名空间或集群可能与Okteto上下文不同，尤其是当同一台机器上运行多个agent或工作树时。运行

okteto kubeconfig

下载Okteto上下文所选集群的凭据，并在每个kubectl命令后添加

-n "$ns"

。如果

kubectl get pods -n "$ns"

报错或显示的Pod与

okteto.yaml

中的服务不匹配，请先修复kubeconfig，再信任任何诊断输出。

Step 2: Discover services

步骤2：发现服务

bash

cat okteto.yaml

Parse the

deploy

and

dev

sections for canonical service names. Never hardcode service names — always derive them from

okteto.yaml

bash

cat okteto.yaml

解析

deploy

和

dev

部分，获取标准服务名称。请勿硬编码服务名称——始终从

okteto.yaml

中提取。

Step 3: Snapshot pod states

步骤3：快照Pod状态

bash

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.

bash

kubectl get pods -n "$ns"

这是核心诊断信号。将每个Pod映射到以下状态之一，并应用对应的处理手册：

Pod状态	处理手册
`CrashLoopBackOff`	崩溃循环
`OOMKilled`	内存溢出终止
`ImagePullBackOff` / `ErrImagePull`	镜像拉取失败
`Pending` （超过60秒）	无法调度
`Running` 但未提供服务/健康检查失败	运行时错误
无Pod存在/部署从未完成	部署失败
所有Pod均为 `Running` 且 `Ready`	同步/开发模式问题

如果用户指定了特定服务，请仅筛选该服务的Pod。如果未指定服务，请检查所有Pod。

Playbooks

处理手册

Crash loop (CrashLoopBackOff)

崩溃循环（CrashLoopBackOff）

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

bash

undefined

容器启动后崩溃，Kubernetes持续重启它。

bash

undefined

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:**
- Exit code in `kubectl describe pod` — `Exit Code: 1` is an app error; `Exit Code: 137` is OOM (see OOM playbook); `Exit Code: 126/127` means the entrypoint command wasn't found
- The last lines of `--previous` logs — the final error before crash is usually the root cause
- Liveness probe failures in `kubectl describe pod` events section — misconfigured health check paths or timeouts

**Common root causes:**
- Missing or wrong environment variable (`fatal: required env var FOO not set`)
- Can't connect to a dependency (database, message queue) that isn't ready yet
- Port mismatch between app and probe configuration
- Command/entrypoint not found (wrong base image or typo in okteto.yaml `command`)

---

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


**需关注：**
- `kubectl describe pod`中的退出码——`Exit Code: 1`为应用错误；`Exit Code: 137`为内存溢出（参考内存溢出处理手册）；`Exit Code: 126/127`表示入口命令未找到
- `--previous`日志的最后几行——崩溃前的最终错误通常是根本原因
- `kubectl describe pod`事件部分中的存活探针失败——健康检查路径或超时配置错误

**常见根本原因：**
- 缺失或错误的环境变量（`fatal: required env var FOO not set`）
- 无法连接到尚未就绪的依赖项（数据库、消息队列）
- 应用与探针配置的端口不匹配
- 命令/入口未找到（基础镜像错误或okteto.yaml中`command`存在拼写错误）

---

OOM kill (OOMKilled)

内存溢出终止（OOMKilled）

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

bash

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

Look for:

```
OOMKilled
```
in the
```
Last State
```
section
```
limits.memory
```
value under
```
Containers
```
→
```
Limits
```
Compare limit to how much memory the service actually needs

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.

容器超出内存限制，被Kubernetes终止。

bash

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

需关注：

```
Last State
```
部分中的
```
OOMKilled
```
标记
```
Containers
```
→
```
Limits
```
下的
```
limits.memory
```
值
将限制值与服务实际所需内存进行对比

修复方案： 在服务的Helm配置或

okteto.yaml

中增加内存限制。向用户显示当前的精确限制值，并建议合理的增量（通常为2倍）。请勿建议完全移除限制。

Image pull failure

镜像拉取失败

Kubernetes can't pull the container image.

bash

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

Look for:

```
Failed to pull image
```
in the Events section
The exact image reference Kubernetes tried to pull (registry, repo, tag)
```
ImagePullBackOff
```
vs
```
ErrImagePull
```
— both mean the same thing, different retry states

Common root causes:

Image doesn't exist (typo in tag, or
```
okteto build
```
was never run for this service)
Image exists but is in a private registry with no pull credentials
Tag was deleted or overwritten after a bad push

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.

Kubernetes无法拉取容器镜像。

bash

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

需关注：

Events部分中的
```
Failed to pull image
```
信息
Kubernetes尝试拉取的镜像完整引用（ registry、仓库、标签）
```
ImagePullBackOff
```
与
```
ErrImagePull
```
——两者含义相同，仅重试状态不同

常见根本原因：

镜像不存在（标签拼写错误，或未针对此服务运行
```
okteto build
```
）
镜像存在但位于私有registry且无拉取凭据
标签在错误推送后被删除或覆盖

修复方案： 如果镜像应由Okteto构建，运行

okteto build <service>

。如果镜像是外部镜像，验证标签是否存在。如果是凭据问题，帮助用户创建镜像拉取密钥。

Pending / unschedulable

Pending / 无法调度

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

bash

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

Pod已被Kubernetes接受，但尚未调度到节点上。

bash

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:**
- `Insufficient cpu` or `Insufficient memory` — node has no room; check resource requests
- `0/N nodes are available` — no node matches the scheduling constraints
- `node(s) had untolerated taint` — pod needs a toleration for a taint on the nodes
- `node(s) didn't match node affinity/selector` — nodeSelector or affinity rules are too strict
- Resource quota exceeded — check `kubectl describe resourcequota -n "$ns"`

**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.

---

kubectl get events -n "$ns" --sort-by=.lastTimestamp | tail -20


**在`kubectl describe pod` → Events中需关注：**
- `Insufficient cpu`或`Insufficient memory`——节点资源不足；检查资源请求配置
- `0/N nodes are available`——无节点匹配调度约束
- `node(s) had untolerated taint`——Pod需要节点污点容忍配置
- `node(s) didn't match node affinity/selector`——nodeSelector或亲和规则过于严格
- 超出资源配额——检查`kubectl describe resourcequota -n "$ns"`

**修复方案：**
根据错误匹配对应的约束。对于资源请求，降低请求值或建议用户扩容节点池。对于污点/选择器，显示当前约束并建议移除或修正。

---

Runtime error (Running but unhealthy)

运行时错误（Running但状态异常）

Pods are

Running

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

bash

undefined

Pod处于

Running

状态，但服务无响应、健康检查失败，或用户在请求中看到错误。

bash

undefined

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:**
- Stack traces or `panic:` lines — note the source file and line number
- Connection refused / timeout errors to dependencies — service is up but a downstream is not
- HTTP 5xx errors logged by a middleware or proxy
- "address already in use" — port conflict inside the container

**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.

---

okteto logs <service> --tail 200 -n "$ns"


**需关注：**
- 堆栈跟踪或`panic:`行——记录源文件和行号
- 依赖项连接被拒绝/超时错误——服务已启动但下游依赖未就绪
- 中间件或代理记录的HTTP 5xx错误
- "address already in use"——容器内部端口冲突

**修复方案：**
引用最相关的5-10行堆栈跟踪或错误信息。如果有文件名，标识出来。建议具体的修复方式——代码变更、缺失的环境变量，或需要启动的依赖服务。

---

Deploy failure

部署失败

The pods never appeared —

okteto deploy

failed before creating them.

bash

undefined

Pod从未出现——

okteto deploy

在创建Pod之前失败。

bash

undefined

Check if the manifest is valid first

先检查清单是否有效

okteto validate

Check deploy logs if validate passes

如果验证通过，检查部署日志

okteto logs --deploy -n "$ns"


**Look for:**
- `okteto validate` errors — YAML syntax, schema violations, missing required fields
- Helm template rendering errors in deploy logs
- Image build failures (Dockerfile errors, build context too large)

**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.

---

okteto logs --deploy -n "$ns"


**需关注：**
- `okteto validate`错误——YAML语法、架构违规、缺失必填字段
- 部署日志中的Helm模板渲染错误
- 镜像构建失败（Dockerfile错误、构建上下文过大）

**修复方案：**
如果`okteto validate`检测到问题，显示精确错误和行号。如果是Helm错误，显示模板路径。如果是构建错误，显示Dockerfile中失败的阶段。

---

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.

bash

okteto status -n "$ns"

所有Pod均为

Running

且

Ready

，但开发者的代码变更未反映在开发容器中。

okteto status

会报告当前开发容器的文件同步状态。该命令仅在

okteto up <service>

会话运行时有效——如果会话未运行，则没有同步操作；请告知用户启动该会话。

bash

okteto status -n "$ns"

If the summary isn't enough, get syncthing troubleshooting links

如果摘要信息不足，获取syncthing故障排查链接

okteto status --info -n "$ns"


**Look for:**
- `Sync status: error` or `Sync status: paused`
- File counts that aren't progressing
- A path in the sync output that doesn't match the actual source directory

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.

---

okteto status --info -n "$ns"


**需关注：**
- `Sync status: error`或`Sync status: paused`
- 文件计数未增长
- 同步输出中的路径与实际源目录不匹配

最丰富的信号来自`okteto up`终端本身——同步错误和冲突警告会首先在那里显示，而您无法查看该会话。请用户粘贴该终端的输出。

**修复方案：**
检查`okteto.yaml`中的`sync`路径与实际目录结构是否匹配。如果路径正确，尝试运行`okteto down`后再执行`okteto up <service>`（用户必须交互式运行`okteto up`——请勿自行运行）。如果同步卡住，`okteto doctor`会生成诊断包。

---

Output format

输出格式

Always emit one block per unhealthy service:

undefined

每个异常服务需输出一个区块：

undefined

Diagnosis: <service-name>

诊断结果: <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:
- The container has only crashed once (no `--previous` logs available)
- The error message is ambiguous or missing
- Multiple possible root causes match the evidence

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.

---

根本原因: <一句话总结> 证据: <日志或describe输出的相关片段——5至20行，请勿超出> 修复方案: <需执行的精确命令或需修改的代码> 置信度: 高 / 中 / 低


在以下情况使用**低**置信度：
- 容器仅崩溃一次（无`--previous`日志可用）
- 错误消息模糊或缺失
- 多个可能的根本原因与证据匹配

如果所有Pod均健康，输出：

所有服务均处于Running且Ready状态。未检测到明显故障。

如果您仍遇到问题，请运行

okteto doctor

生成完整诊断包。

---

Common gotchas

常见注意事项

kubectl and okteto can disagree — kubectl uses its own kubeconfig context, which may point at a different namespace or cluster than the Okteto context. If kubectl output doesn't match what
```
okteto
```
commands report, run
```
okteto kubeconfig
```
and re-check with
```
-n "$ns"
```
before drawing any conclusion.
kubectl logs --previous
fails on first crash — the container must have restarted at least once. Fall back to
```
kubectl logs
```
(current instance) or describe events.
Exit code 137 = OOM, not app error — if you see
```
exit code: 137
```
in a CrashLoopBackOff, treat it as OOM kill, not a crash loop.

Pending
pods don't have logs — skip

kubectl logs

entirely and go straight to

kubectl describe pod

kubectl get events

okteto logs
vs
kubectl logs
— prefer
```
okteto logs
```
for application output; use
```
kubectl logs
```
when you need
```
--previous
```
or when the pod name is needed for
```
describe
```
.
Never run
okteto destroy
as part of debugging — diagnose first. Only suggest teardown if the environment is unrecoverable and the user explicitly asks.
Never run
okteto up
— it is interactive. If the fix requires re-entering dev mode, tell the user to run
```
okteto up <service>
```
in their terminal.

kubectl与okteto可能不一致——kubectl使用自身的kubeconfig上下文，其指向的命名空间或集群可能与Okteto上下文不同。如果kubectl输出与
```
okteto
```
命令报告的内容不匹配，请先运行
```
okteto kubeconfig
```
并添加
```
-n "$ns"
```
重新检查，再得出结论。
首次崩溃时
kubectl logs --previous
会失败——容器必须至少重启一次。请回退到
```
kubectl logs
```
（当前实例）或查看describe事件。
退出码137=内存溢出，而非应用错误——如果在CrashLoopBackOff中看到
```
exit code: 137
```
，请按内存溢出终止处理，而非崩溃循环。
Pending状态的Pod无日志——完全跳过
```
kubectl logs
```
，直接执行
```
kubectl describe pod
```
+
```
kubectl get events
```
。
okteto logs
vs
kubectl logs
——优先使用
```
okteto logs
```
获取应用输出；当需要
```
--previous
```
或Pod名称用于
```
describe
```
时，使用
```
kubectl logs
```
。
调试时请勿运行
okteto destroy
——先诊断。仅当环境无法恢复且用户明确要求时，才建议销毁。
请勿运行
okteto up
——该命令为交互式命令。如果修复需要重新进入开发模式，请告知用户在终端中运行
```
okteto up <service>
```
。