Troubleshoot your Okteto instance
Welcome to the Okteto troubleshooting guide. This page provides answers to some common issues encountered while using Okteto. Please also review our FAQ Guide for additional help.
How to extract logs from Okteto when asking for help
For Developers
Run okteto doctor to generate a doctor file with the Okteto logs for a Development Container. Attach it when you contact Okteto support or ask in the Okteto Community.
For Administrators of Okteto
Use the Okteto Diagnostics tool to create a support bundle with cluster information, logs for the Okteto components, and other relevant information.
How to Check That Your Okteto Instance is Healthy
1. Sanity check the Okteto Helm release
Run these commands to check the status of your Okteto Helm release:
helm list -n okteto
helm get values "okteto" -n okteto -o yaml
The commands return output like this:
- helm list
- helm get values
~ % helm list
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
okteto okteto 22 2025-10-02 10:26:07.428432 -0400 EDT deployed okteto-1.36.0 464e721e7
~ % helm get values "okteto" -n okteto -o yaml
buildkit:
persistence:
enabled: true
ingress:
annotations:
nginx.ingress.kubernetes.io/proxy-send-timeout: 180
ingress-nginx:
controller:
config:
large-client-header-buffers: 4 100k
proxy-connect-timeout: "180"
proxy-read-timeout: "180"
proxy-send-timeout: "180"
extraArgs:
default-ssl-certificate: $(POD_NAMESPACE)/okteto-letsencrypt
insights:
enabled: true
license: <LICENSE>
okteto-nginx:
controller:
config:
large-client-header-buffers: 4 100k
proxy-connect-timeout: "180"
proxy-read-timeout: "180"
proxy-send-timeout: "180"
registry:
storage:
filesystem:
persistence:
enabled: true
subdomain: jona.okteto.me
wildcardCertificate:
create: false
name: okteto-letsencrypt
2. Wait for workloads to become "Available"
Check that all Deployments and StatefulSets have completed their rollouts and that all Pods are in the Ready state:
# Deployments & StatefulSets rollouts
kubectl rollout status deploy -l app.kubernetes.io/instance="okteto" -n okteto --timeout=120s
kubectl rollout status sts -l app.kubernetes.io/instance="okteto" -n okteto --timeout=120s
# All pods to Ready (every container ready)
kubectl wait pod -l app.kubernetes.io/instance="okteto" -n okteto --for=condition=Ready --timeout=180s
If a command times out, go to 8. Anything looks bad? to investigate.
3. Spot Unhealthy Pods
Check for Pods that aren't Ready or that have container restarts:
# Pods not Ready
kubectl get pods -l app.kubernetes.io/instance="okteto" -n okteto --field-selector=status.phase!=Running -o wide
# Restarts > 0
kubectl get pods -l app.kubernetes.io/instance="okteto" -n okteto -o custom-columns='POD:.metadata.name,READY:.status.containerStatuses[*].ready,RESTARTS:.status.containerStatuses[*].restartCount'| (read; echo "$REPLY"; sort -k3 -nr)
4. Inventory resources created by Okteto Helm release
Check that every resource the Okteto Helm release creates is healthy:
kubectl get all -l app.kubernetes.io/instance="okteto" -n okteto
kubectl get ingress,service -l app.kubernetes.io/instance="okteto" -n okteto
kubectl get cm,secret,pvc -l app.kubernetes.io/instance="okteto" -n okteto
The commands return output like this:
- kubectl get all
- kubectl get ingress,service
- kubectl get cm,secret,pvc
~ % kubectl get all -l app.kubernetes.io/instance="okteto" -n okteto
NAME READY STATUS RESTARTS AGE
pod/okteto-api-d6ccbfc8d-8fgb5 1/1 Running 0 3m7s
pod/okteto-api-d6ccbfc8d-bqrlp 1/1 Running 0 3m7s
pod/okteto-buildkit-8c96f331e1-0 1/1 Running 0 3m5s
pod/okteto-daemon-ggbh2 1/1 Running 0 3m8s
pod/okteto-daemon-hr8w4 1/1 Running 0 3m8s
pod/okteto-eventsexporter-0 1/1 Running 0 3m4s
pod/okteto-frontend-56d6fc4696-rblcn 1/1 Running 0 3m6s
pod/okteto-frontend-56d6fc4696-vlv5f 1/1 Running 0 3m6s
pod/okteto-ingress-nginx-controller-7bd8f79fbc-79gjs 1/1 Running 0 3m7s
pod/okteto-ingress-nginx-controller-7bd8f79fbc-hc9cq 1/1 Running 0 3m7s
pod/okteto-ingress-nginx-defaultbackend-88d58c8bd-9xr9g 1/1 Running 0 3m6s
pod/okteto-ingress-nginx-defaultbackend-88d58c8bd-z7zlf 1/1 Running 0 3m6s
pod/okteto-mutation-webhook-66548b9669-t9rcb 1/1 Running 0 3m5s
pod/okteto-mutation-webhook-66548b9669-z6k6w 1/1 Running 0 3m4s
pod/okteto-okteto-nginx-controller-7bb7686cdb-k5h5t 1/1 Running 0 3m7s
pod/okteto-okteto-nginx-controller-7bb7686cdb-w6jh9 1/1 Running 0 3m7s
pod/okteto-prepullimages-86c2t 4/4 Running 0 3m8s
pod/okteto-prepullimages-nt9g7 4/4 Running 0 3m8s
pod/okteto-redis-5998c6c5f4-c549r 1/1 Running 0 3m6s
pod/okteto-regcreds-6c7444697-4tvmh 1/1 Running 0 3m5s
pod/okteto-regcreds-6c7444697-r5r24 1/1 Running 0 3m6s
pod/okteto-registry-565bd4ff94-9skgf 1/1 Running 0 3m5s
pod/okteto-reloader-54d478cbbd-bzjb2 1/1 Running 0 3m7s
pod/okteto-ssh-agent-59dd765ff-5kk89 1/1 Running 0 3m5s
pod/okteto-ssh-agent-59dd765ff-kr4vt 1/1 Running 0 3m5s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/okteto-api ClusterIP 34.118.228.121 <none> 8080/TCP 3m11s
service/okteto-buildkit ClusterIP 34.118.232.126 <none> 443/TCP 3m11s
service/okteto-cluster-endpoint ExternalName <none> kubernetes.default.svc.cluster.local 443/TCP 3m9s
service/okteto-eventsexporter ClusterIP 34.118.227.140 <none> 8080/TCP 3m10s
service/okteto-frontend ClusterIP 34.118.230.239 <none> 8080/TCP 3m10s
service/okteto-ingress-nginx-controller LoadBalancer 34.118.239.1 34.11.21.218 80:32340/TCP,443:31322/TCP 3m12s
service/okteto-ingress-nginx-defaultbackend ClusterIP 34.118.238.41 <none> 80/TCP 3m10s
service/okteto-mutation-webhook ClusterIP 34.118.232.212 <none> 443/TCP 3m8s
service/okteto-okteto-nginx-controller ClusterIP 34.118.232.157 <none> 80/TCP,443/TCP 3m11s
service/okteto-redis ClusterIP 34.118.238.162 <none> 6379/TCP 3m9s
service/okteto-regcreds ClusterIP 34.118.230.229 <none> 443/TCP 3m9s
service/okteto-registry ClusterIP 34.118.227.250 <none> 5000/TCP 3m9s
service/okteto-ssh-agent ClusterIP 34.118.230.24 <none> 3000/TCP 3m8s
NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE
daemonset.apps/okteto-daemon 2 2 2 2 2 <none> 3m8s
daemonset.apps/okteto-prepullimages 2 2 2 2 2 <none> 3m8s
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/okteto-api 2/2 2 2 3m7s
deployment.apps/okteto-frontend 2/2 2 2 3m6s
deployment.apps/okteto-ingress-nginx-controller 2/2 2 2 3m8s
deployment.apps/okteto-ingress-nginx-defaultbackend 2/2 2 2 3m7s
deployment.apps/okteto-mutation-webhook 2/2 2 2 3m5s
deployment.apps/okteto-okteto-nginx-controller 2/2 2 2 3m7s
deployment.apps/okteto-redis 1/1 1 1 3m6s
deployment.apps/okteto-regcreds 2/2 2 2 3m6s
deployment.apps/okteto-registry 1/1 1 1 3m6s
deployment.apps/okteto-reloader 1/1 1 1 3m7s
deployment.apps/okteto-ssh-agent 2/2 2 2 3m5s
NAME DESIRED CURRENT READY AGE
replicaset.apps/okteto-api-d6ccbfc8d 2 2 2 3m7s
replicaset.apps/okteto-frontend-56d6fc4696 2 2 2 3m6s
replicaset.apps/okteto-ingress-nginx-controller-7bd8f79fbc 2 2 2 3m7s
replicaset.apps/okteto-ingress-nginx-defaultbackend-88d58c8bd 2 2 2 3m6s
replicaset.apps/okteto-mutation-webhook-66548b9669 2 2 2 3m5s
replicaset.apps/okteto-okteto-nginx-controller-7bb7686cdb 2 2 2 3m7s
replicaset.apps/okteto-redis-5998c6c5f4 1 1 1 3m6s
replicaset.apps/okteto-regcreds-6c7444697 2 2 2 3m6s
replicaset.apps/okteto-registry-565bd4ff94 1 1 1 3m5s
replicaset.apps/okteto-reloader-54d478cbbd 1 1 1 3m7s
replicaset.apps/okteto-ssh-agent-59dd765ff 2 2 2 3m5s
NAME READY AGE
statefulset.apps/okteto-buildkit-8c96f331e1 1/1 3m5s
statefulset.apps/okteto-eventsexporter 1/1 3m5s
NAME SCHEDULE TIMEZONE SUSPEND ACTIVE LAST SCHEDULE AGE
cronjob.batch/okteto-destroy-all-checker */3 * * * * <none> False 0 103s 3m5s
cronjob.batch/okteto-gc @hourly <none> False 0 <none> 3m5s
cronjob.batch/okteto-insights-metrics */5 * * * * <none> False 0 103s 3m5s
cronjob.batch/okteto-installer-checker */5 * * * * <none> False 0 103s 3m5s
cronjob.batch/okteto-periodic-metrics @hourly <none> False 0 <none> 3m4s
cronjob.batch/okteto-resourcemanager */5 * * * * <none> False 0 103s 3m4s
cronjob.batch/okteto-telemetry @daily <none> False 0 <none> 3m4s
~ % kubectl get ingress,service -l app.kubernetes.io/instance="okteto" -n okteto
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/okteto okteto-controlplane-nginx okteto.jona.okteto.me 34.21.79.137 80, 443 202d
ingress.networking.k8s.io/okteto-buildkit okteto-controlplane-nginx buildkit.jona.okteto.me 34.21.79.137 80, 443 202d
ingress.networking.k8s.io/okteto-cluster-endpoint okteto-controlplane-nginx kubernetes.jona.okteto.me 34.21.79.137 80, 443 202d
ingress.networking.k8s.io/okteto-registry okteto-controlplane-nginx registry.jona.okteto.me 34.21.79.137 80, 443 202d
ingress.networking.k8s.io/okteto-wildcard okteto-controlplane-nginx *.jona.okteto.me 34.21.79.137 80, 443 202d
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/okteto-api ClusterIP 34.118.233.67 <none> 8080/TCP 202d
service/okteto-buildkit ClusterIP 34.118.236.79 <none> 443/TCP 202d
service/okteto-cluster-endpoint ExternalName <none> kubernetes.default.svc.cluster.local 443/TCP 202d
service/okteto-eventsexporter ClusterIP 34.118.230.3 <none> 8080/TCP 202d
service/okteto-frontend ClusterIP 34.118.232.147 <none> 8080/TCP 202d
service/okteto-ingress-nginx-controller LoadBalancer 34.118.231.219 34.21.79.137 80:31270/TCP,443:32017/TCP 202d
service/okteto-ingress-nginx-defaultbackend ClusterIP 34.118.230.224 <none> 80/TCP 202d
service/okteto-mutation-webhook ClusterIP 34.118.233.42 <none> 443/TCP 202d
service/okteto-okteto-nginx-controller ClusterIP 34.118.228.30 <none> 80/TCP,443/TCP 202d
service/okteto-redis-headless ClusterIP None <none> 6379/TCP 202d
service/okteto-redis-master ClusterIP 34.118.228.154 <none> 6379/TCP 202d
service/okteto-regcreds ClusterIP 34.118.226.123 <none> 443/TCP 202d
service/okteto-registry ClusterIP 34.118.225.14 <none> 5000/TCP 202d
service/okteto-ssh-agent ClusterIP 34.118.232.197 <none> 3000/TCP 202d
~ % kubectl get cm,secret,pvc -l app.kubernetes.io/instance="okteto" -n okteto
NAME DATA AGE
configmap/okteto 167 202d
configmap/okteto-helm-release-meta 6 91d
configmap/okteto-ingress-config 1 202d
configmap/okteto-ingress-nginx-controller 15 202d
configmap/okteto-okteto-nginx-controller 14 202d
configmap/okteto-preflight 1 202d
configmap/okteto-redactor 1 202d
configmap/okteto-redis-configuration 4 202d
configmap/okteto-redis-health 6 202d
configmap/okteto-redis-scripts 1 202d
configmap/okteto-registry-config 1 202d
configmap/okteto-support-bundle 1 202d
NAME TYPE DATA AGE
secret/okteto Opaque 2 202d
secret/okteto-mutation-webhook kubernetes.io/tls 3 202d
secret/okteto-regcreds kubernetes.io/tls 3 202d
secret/okteto-registry-http-secret Opaque 1 202d
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
persistentvolumeclaim/storage-okteto-buildkit-7c80387317-0 Bound pvc-79219185-22de-4ccb-acd8-3228b3bb7323 100Gi RWO standard-rwo <unset> 86d
persistentvolumeclaim/storage-okteto-buildkit-7c80387317-1 Bound pvc-9e19e7f8-6f2f-4685-8a2d-dc340f4639e1 100Gi RWO standard-rwo <unset> 86d
5. Check that services have endpoints
Verify that every Service has healthy Endpoints:
kubectl get svc -l app.kubernetes.io/instance="okteto" -n okteto
kubectl get endpoints -l app.kubernetes.io/instance="okteto" -n okteto
The commands return output like this:
- kubectl get svc
- kubectl get endpoints
~ % kubectl get svc -l app.kubernetes.io/instance="okteto" -n okteto
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
okteto-api ClusterIP 34.118.233.67 <none> 8080/TCP 234d
okteto-buildkit ClusterIP 34.118.236.79 <none> 443/TCP 234d
okteto-cluster-endpoint ExternalName <none> kubernetes.default.svc.cluster.local 443/TCP 234d
okteto-eventsexporter ClusterIP 34.118.230.3 <none> 8080/TCP 234d
okteto-frontend ClusterIP 34.118.232.147 <none> 8080/TCP 234d
okteto-ingress-nginx-controller LoadBalancer 34.118.231.219 34.21.79.137 80:31270/TCP,443:32017/TCP 234d
okteto-ingress-nginx-defaultbackend ClusterIP 34.118.230.224 <none> 80/TCP 234d
okteto-mutation-webhook ClusterIP 34.118.233.42 <none> 443/TCP 234d
okteto-okteto-nginx-controller ClusterIP 34.118.228.30 <none> 80/TCP,443/TCP 234d
okteto-redis ClusterIP 34.118.227.133 <none> 6379/TCP 20d
okteto-regcreds ClusterIP 34.118.226.123 <none> 443/TCP 234d
okteto-registry ClusterIP 34.118.225.14 <none> 5000/TCP 234d
okteto-ssh-agent ClusterIP 34.118.232.197 <none> 3000/TCP 234d
~ % kubectl get endpoints -l app.kubernetes.io/instance="okteto" -n okteto
NAME ENDPOINTS AGE
okteto-api 10.112.0.9:8080,10.112.2.16:8080 234d
okteto-buildkit 10.112.2.29:1234 234d
okteto-eventsexporter 10.112.0.215:8080 234d
okteto-frontend 10.112.0.10:8080,10.112.2.17:8080 234d
okteto-ingress-nginx-controller 10.112.0.11:443,10.112.2.18:443,10.112.0.11:80 + 1 more... 234d
okteto-ingress-nginx-defaultbackend 10.112.0.16:8080,10.112.2.19:8080 234d
okteto-mutation-webhook 10.112.0.13:8443,10.112.2.20:8443 234d
okteto-okteto-nginx-controller 10.112.0.15:443,10.112.2.21:443,10.112.0.15:80 + 1 more... 234d
okteto-redis 10.112.0.14:6379 20d
okteto-regcreds 10.112.0.17:9443,10.112.2.22:9443 234d
okteto-registry 10.112.2.30:5000 234d
okteto-ssh-agent 10.112.0.19:3000,10.112.2.23:3000 234d
6. Validate your DNS configuration
Verify that the Okteto subdomain resolves and is reachable:
curl -i --max-time 5 "https://okteto.<Okteto instance subdomain>/healthz"
7. Test your Okteto Instance End-to-End
Run okteto build, okteto deploy, and okteto up with the Movies sample to check that Okteto deployments work end to end:
git clone https://github.com/okteto/movies
cd movies
okteto build
okteto deploy
okteto up
8. Anything looks bad?
Check the events, and describe the failing Pods or other resources to find out what's wrong:
# a) Events (cluster is telling you what’s wrong)
kubectl get events -n okteto --sort-by=.lastTimestamp | tail -n 40
# b) Describe the failing thing (image pulls, scheduling, probe failures)
kubectl describe pod <pod-name>
Daemon fails with "open /etc/hosts: permission denied"
The node's operating system doesn't allow Okteto to modify the /etc/hosts file. Okteto needs write access to /etc/hosts on the cluster nodes to configure internal registry resolution. When it can't write to it, the okteto-daemon pods fail with an error like this one:
{"level":"fatal","service":"daemon","error":"open /etc/hosts: permission denied","timestamp":"...","message":"tasks initialization failed"}
This commonly happens with an unsupported node OS, such as Bottlerocket on AWS EKS. Bottlerocket uses a read-only root filesystem, which prevents Okteto from writing to /etc/hosts.
To fix it:
- Switch to a supported node OS. On AWS EKS, use Amazon Linux 2023 (AL2023) or Amazon Linux 2 (AL2). The Amazon EKS installation requirements have the details.
- Recreate your node group with the supported AMI family. For example, using
eksctl:eksctl create nodegroup \--cluster="${CLUSTER_NAME}" \--region="${AWS_REGION}" \--node-type="m5.xlarge" \--node-ami-family="AmazonLinux2023" - Drain and delete the old node group running the unsupported OS.
UPGRADE FAILED: "okteto" has no deployed releases
This error occurs on your second install or upgrade when your initial install failed. Delete the failed install before you try again:
helm uninstall okteto --namespace okteto
Registry pods keep restarting
The usual cause is that the registry pods can't read from or write to your cloud storage bucket. Check that the cloud IAM you created has read and write access to the bucket.
Deployment pipelines stay in "progressing" forever
A pipeline can get stuck for several reasons: for example, the installer job couldn't start because of an error in the Kubernetes API, or because the cluster is overloaded. To find the problem, list the jobs and pods for the pipeline.
You need the pipeline name (the name displayed in the Okteto UI) and the Namespace where it's deployed. For example, for the movies pipeline in the cindy Namespace, list its jobs and pods with these commands:
kubectl get jobs -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto
kubectl get pods -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindy --namespace=okteto
Using a Custom CNI
If your cluster uses a custom CNI, the webhooks may need additional configuration. In some cases, the CNI on the worker nodes isn't the same as the CNI of the control plane, and the webhooks need host networking. The ports may also need to change to avoid collisions.
The Okteto Webhook is configured by settingwebhook.hostNetwork to true. The ports are set with webhook.port.
More information on the Okteto Webhook configuration can be found here.
Docker Hub credentials misconfiguration
Okteto lets you configure your own Docker Hub account. If its credentials are wrong, kubelet can't pull public images from Docker Hub, which can cause serious issues in the cluster.
To fix it:
- Update the container image used by the daemonset pods. Use a container registry other than Docker Hub, so the pods pull the image without the credential problem. For example,
ghcr.io/okteto/busybox. - Change or remove the credentials for the Docker Hub registry.
- Upgrade your Okteto instance with the new configuration.
The Okteto daemonset then configures the right credentials for Docker Hub. Once you verify that everything works, you can restore the original base image for the Okteto daemonset.
Community help
Reach out to us, we're always happy to help!