Troubleshooting
Something is broken
The rest of this site is organised by subject, which is the wrong shape when something is actually failing. These pages start from the error you are looking at.
Each page names every cause it knows about and gives you a command that confirms or rules out each one. Nothing here can see your cluster, so nothing here is presented as a certainty — you check, and the page tells you what to look for.
Terraform
- Error acquiring the state lockSomething holds the lock. Usually a run that was killed before it could release — but possibly a run that is still very much alive, and `force-unlock` on that one can corrupt your state. The whole question is which.4 causes · 3 diagnostic steps
- Terraform wants to change something nobody changedA plan proposes changes to resources you did not touch. Either reality moved out from under the state — somebody changed it in a console — or the provider is reporting a difference that is not really a difference. The two look identical in a plan and need opposite responses.5 causes · 3 diagnostic steps
HTTP
- 502 Bad GatewayThe proxy could not get a usable response from the thing behind it. The proxy is reporting a fact about somebody else — so the answer is almost never in the proxy's configuration, and almost always in whether the upstream was reachable, alive, and speaking HTTP.6 causes · 3 diagnostic steps
- 504 Gateway TimeoutThe upstream was reachable and never finished in time. Unlike a 502, nothing failed — the proxy gave up waiting, which means the answer is either a slow upstream or a timeout set below how long the work honestly takes.5 causes · 3 diagnostic steps
Docker
- Container exits immediatelyThe container starts, the process finishes, and Docker stops the container — because a container lives exactly as long as its main process. The exit code tells you which of two quite different situations you are in.5 causes · 3 diagnostic steps
- Bind for 0.0.0.0:PORT failed: port is already allocatedSomething already holds the host port you asked to publish. Usually another container — sometimes a stopped one that still owns the binding, and sometimes a process on the host that has nothing to do with Docker.4 causes · 3 diagnostic steps
- Connection refused between containersAlmost always one of three things: using `localhost` when you mean the other container's name, the containers not sharing a network, or the target application bound to its own loopback so nothing outside the container can reach it.5 causes · 3 diagnostic steps
- no space left on deviceDocker has filled the filesystem, and almost always with things nothing is using: build cache, dangling images, stopped containers and orphaned volumes. Deleting containers does not reclaim their volumes, which is why the space does not come back.5 causes · 3 diagnostic steps
Kubernetes
- CrashLoopBackOffA container starts, exits, and Kubernetes restarts it — repeatedly. The loop itself is not the fault; it is the symptom of whatever makes the container exit.5 causes · 3 diagnostic steps
- OOMKilled (exit code 137)The kernel terminated your container for exceeding its memory limit. Exit code 137 is the signature, and the only question that matters is whether the limit is too low or the application is leaking.4 causes · 3 diagnostic steps
- ImagePullBackOffThe kubelet cannot retrieve the container image, and is now backing off between attempts. Almost always the name, the credentials, or the network — in that order of likelihood.5 causes · 3 diagnostic steps
- Pod stuck in PendingThe pod exists in the API but no node has accepted it. Nothing is running yet, so logs are empty — the answer is always in the scheduler's own explanation.5 causes · 3 diagnostic steps
An error you cannot find here? Ask it — the catalogue grows from what people actually hit.