Troubleshooting Guides
Paste the error, get the fix.
Each of these starts from a real error message and works through the causes in the order they actually occur in production — with the command to confirm which one you're hitting before you change anything.
21 articles in this series
- 016 min
Fix AWS EC2 Instance Unreachable: Can't SSH In
EC2 instance unreachable via SSH? The cause is almost always Security Group rules, Network ACLs, a missing public IP, or a failed boot. Here's a systematic diagnostic flow — including SSM Session Manager as a fallback when SSH isn't an option.
Read - 025 min
Fix Docker 'no space left on device' Error
Docker's 'no space left on device' error almost always means the build cache, stopped containers, or dangling images have filled the disk — not your actual application data. Here's how to reclaim the space in under 2 minutes.
Read - 039 min
Fix Docker 'permission denied ... /var/run/docker.sock'
The 'permission denied while trying to connect to the Docker daemon socket' error means your user can't talk to the Docker daemon. Here's why it happens and how to fix it properly — without just slapping sudo on everything.
Read - 044 min
Fix Git 'refusing to merge unrelated histories'
Git refuses to merge branches that have no common commit ancestor. It happens when you git init a project locally and then try to pull from a GitHub repo that was initialized with a README. One flag fixes it.
Read - 055 min
Fix Git Detached HEAD State
Detached HEAD means Git's HEAD pointer points directly at a commit instead of a branch. Commits made in this state belong to no branch and can be lost. Here's how to get back to a branch and how to rescue commits you already made.
Read - 065 min
Fix Git Push Rejected: Updates Were Rejected
Git rejects your push when the remote has commits your local branch doesn't have. The safe fix is to pull first and integrate those changes — not force push. Here's the full diagnostic and fix guide.
Read - 079 min
Fix Helm 'another operation (install/upgrade/rollback) is in progress'
Helm refuses to upgrade because a release is stuck in a pending status after a previous command crashed or timed out. Here's how to diagnose the stuck revision and clear it safely.
Read - 087 min
Fix kubectl 'connection to the server localhost:8080 was refused'
The connection to the server localhost:8080 was refused means kubectl has no valid kubeconfig loaded and fell back to a default that points nowhere. It's a client config problem, not a broken cluster. Here's how to fix it.
Read - 099 min
Fix kubectl 'x509: certificate signed by unknown authority'
This error means kubectl can't verify the API server's TLS certificate against the CA in your kubeconfig. Here's how to find which of the five common causes is yours and fix it.
Read - 109 min
Fix Kubernetes 'pod has unbound immediate PersistentVolumeClaims'
Your pod is stuck Pending with 'pod has unbound immediate PersistentVolumeClaims' because its PVC never bound to a PV. Here's how to find out why and fix each root cause.
Read - 119 min
Fix Kubernetes 'Readiness probe failed': Pod Running but Not Ready
Your pod is Running but shows 0/1 Ready, and describe pod reports 'Readiness probe failed'. That means Kubernetes pulled it out of the Service endpoints, so it gets no traffic. Here's how to find the real cause and fix it.
Read - 125 min
Fix Kubernetes CrashLoopBackOff: Container Keeps Restarting
CrashLoopBackOff means your container is crashing on startup and Kubernetes keeps restarting it with an increasing delay. Here's how to diagnose the exact cause and fix it.
Read - 138 min
Fix Kubernetes CreateContainerConfigError
CreateContainerConfigError means the kubelet can't build your container's config because it references a ConfigMap or Secret that's missing, misnamed, or missing a key. Here's how to find the exact reference that's broken and fix it.
Read - 148 min
Fix Kubernetes Exit Code 137 (SIGKILL / OOMKilled)
Exit code 137 means your container was killed by SIGKILL — usually OOMKilled, but not always. Here's how to tell the difference and fix each root cause.
Read - 159 min
Fix Kubernetes FailedScheduling: 0/N nodes are available
A Pod stuck Pending with FailedScheduling means the scheduler looked at every node and rejected all of them. The Events line tells you why — here's how to read it and fix each cause.
Read - 165 min
Fix Kubernetes ImagePullBackOff and ErrImagePull
ImagePullBackOff means Kubernetes can't pull your container image. The real reason is always in the pod events — wrong tag, missing credentials, rate limit, or network issue. Here's how to diagnose and fix each one.
Read - 176 min
Fix Kubernetes Ingress 502 Bad Gateway
A 502 from your Kubernetes Ingress means nginx can't reach the upstream service. The cause is almost always a misconfigured Service port, no ready pods behind the Service, or a label selector mismatch.
Read - 186 min
Fix Kubernetes OOMKilled: Pod Killed Due to Out of Memory
OOMKilled means the Linux kernel terminated your container because it exceeded its memory limit. Here's how to diagnose how much memory your app actually needs, right-size the limit, and stop the kills.
Read - 196 min
Fix Kubernetes Pending Pods: Pod Stuck and Never Scheduled
A pod stuck in Pending means the scheduler can't find a node to place it on. The reason is always in the pod events — insufficient resources, affinity rules, taints, or an unbound PVC.
Read - 206 min
Fix Nginx 'Too Many Open Files' Error
Nginx's 'too many open files' error (errno 24) means a worker process hit its file descriptor limit. The fix requires changes at three levels — nginx.conf, the systemd unit, and the OS — all three are needed.
Read - 218 min
Fix Terraform 'Error acquiring the state lock'
Terraform failed with 'Error acquiring the state lock' and printed a Lock Info block. Here's how to read that block, decide whether to wait or force-unlock, and fix the backend so it stops happening.
Read
Other series
Tool Comparisons
X vs Y, decided on what matters in production.
What Is… Explainers
Plain definitions of terms that get used loosely.
AWS Service Guides
One service at a time, from someone who runs them.
AI & LLM Infrastructure
Running models yourself, and knowing when not to.
CI/CD Pipelines
Building, testing and shipping, without the pipeline owning you.
Kubernetes
The cluster, end to end.