Debugging
Finding out why something broke: reading errors, browser dev tools, logs, and the classic works-locally-fails-in-production gap.
130 posts · page 4 of 5
Git "Detached HEAD" Explained: What It Is and How to Get Out
"You are in 'detached HEAD' state" means you've checked out a specific commit instead of a branch. It's safe to look around; commits made here are easy to lose. How you got there, how to get back, and how to save work you did while detached.
git bisect: Find the Commit That Broke Your App
Something worked last week and doesn't now. git bisect binary-searches your history to find the exact commit that introduced a bug in a handful of steps. Manual bisecting, automating it with git bisect run and a test script, skipping untestable commits, and using it with AI agents.
"TypeError: Failed to Fetch": What It Means and How to Fix It
"Failed to fetch" means the browser couldn't complete a request at all — no response reached your code. The usual causes are CORS, a wrong URL, mixed content, the server being down, or an ad blocker. How to tell which in under a minute.
"exec format error" in Docker: ARM vs x86 Images Explained
exec format error almost always means a container image built for one CPU architecture (ARM, like Apple Silicon Macs) is running on another (x86/amd64 servers), or vice versa. How to check, build for the right platform with --platform and buildx, and the other cause: scripts without a shebang or with Windows line endings.
ESM vs CommonJS: import vs require and the Errors Between Them
JavaScript has two module systems. CommonJS uses require and module.exports; ES modules use import and export. How Node decides which a file is, and how to fix 'Cannot use import statement outside a module', 'require is not defined', ERR_REQUIRE_ESM and __dirname is not defined.
ERR_CONNECTION_REFUSED: What It Means and How to Fix It
Connection refused means your browser reached the computer, but nothing was listening on that port. The causes on localhost (dev server not running, wrong port, crashed) and on a live site (app or web server down, firewall, wrong address), and how to check each.
Why Is My Environment Variable Undefined? (Vite, Next.js, Node)
Your .env file has the value but the code sees undefined. The reasons are almost always the same: the wrong prefix (VITE_, NEXT_PUBLIC_), the wrong file name or folder, not restarting the dev server, build-time vs runtime, or the variable never being set in production.
ECONNREFUSED 127.0.0.1:5432: Why Your App Can't Reach the Database
"connect ECONNREFUSED 127.0.0.1:5432" means nothing was listening where your app tried to connect. The causes: database not running, wrong host inside Docker, wrong port, listening on the wrong address, or a firewall. How to find which, plus the related timeout and authentication errors.
"duplicate key value violates unique constraint": Causes and Fixes
Postgres refused an insert because a value that must be unique already exists. The two very different cases — a real duplicate (like an email that's taken) and an out-of-sync ID sequence after importing data — and how to fix each, including ON CONFLICT and resetting sequences.
Docker "Port Is Already Allocated": How to Find and Free the Port
Docker can't publish a container's port because something on your machine already uses it — often another container, a local Postgres or a dev server. How to find what's using the port on Mac, Linux and Windows, stop it, or simply map the container to a different port.
Docker "Permission Denied While Trying to Connect to the Docker Daemon Socket": Fix
Your user isn't allowed to talk to Docker's socket at /var/run/docker.sock. The quick fix (add yourself to the docker group), why that's effectively root access, the safer rootless alternative, and the other causes: Docker not running, Docker Desktop, WSL and CI.
Docker Container Keeps Restarting: How to Find Out Why
A container stuck in 'Restarting' is crashing on start and being brought back by its restart policy. How to read exit codes (1, 126, 127, 137, 139, 143), get logs from a crash loop, override the entrypoint to look inside, and fix the usual causes: config errors, OOM kills, missing dependencies and failing healthchecks.
DNS_PROBE_FINISHED_NXDOMAIN: What It Means and How to Fix It
NXDOMAIN means DNS says the domain name doesn't exist. Fixes for visitors (typos, DNS cache, changing DNS servers) and for site owners (missing records, nameserver changes, expired domains, propagation), with the commands to check what DNS is really saying.
z-index Not Working? The Real Reasons (Stacking Contexts Explained)
Set z-index: 9999 and the element is still behind something? z-index only works on positioned elements and only within its stacking context. The four common causes, how to spot a stacking context, and the fixes — including portals for modals and dropdowns.
Cloudflare Error 521, 522 and 525: What They Mean and How to Fix Them
Cloudflare's 52x errors mean Cloudflare couldn't talk properly to your server. 521: your server refused the connection. 522: it timed out. 525: the HTTPS handshake failed. How to tell which part is broken and fix it — usually the web server, firewall, or SSL mode.
Claude Code Not Working? Fixes for the Most Common Problems
"command not found: claude", login loops, API errors, rate limits, slow or stuck sessions, permission prompts that never stop, and Claude ignoring your instructions. A troubleshooting guide for the problems people hit most, starting with claude doctor.
"Cannot Find Module" and "Module Not Found": How to Fix Them
Node's "Error: Cannot find module" and bundlers' "Module not found: Can't resolve" mean an import points at something that isn't there. The five causes — not installed, wrong path, wrong case, missing build, wrong working directory — and how to fix each.
504 Gateway Timeout: What It Means and How to Fix It
A 504 means the proxy in front of your app (Nginx, Cloudflare, a load balancer) gave up waiting for a response. The usual causes — slow database queries, long tasks done in the request, external APIs, timeouts set too low — and how to find and fix each.
502 Bad Gateway: What It Means and How to Fix It
A 502 means the server in front of your app (Nginx, Cloudflare, a load balancer) couldn't get a valid answer from your app. The usual causes — app crashed, wrong port, still starting, out of memory — and a step-by-step way to find which one.
500 Internal Server Error: How to Find What Actually Broke
A 500 error means your server-side code threw an error it didn't handle. The page tells you nothing on purpose; the real message is in your logs. Where to look, the most common causes in AI-built apps, and how to stop users seeing a bare 500.
413 Request Entity Too Large: How to Fix Upload Size Limits
A 413 means a request body — usually a file upload — was bigger than a server allows. Where the limits live (Nginx client_max_body_size, Express body parsers, Next.js, Cloudflare, serverless platforms), how to raise them, and why large files should skip your server entirely.
401 vs 403: Unauthorized vs Forbidden, Explained
401 means 'we don't know who you are' — log in or send valid credentials. 403 means 'we know who you are, and you're not allowed'. How to tell them apart, the common causes of each, how to fix them as a user or developer, and when to return 404 instead.
React App Shows a Blank Page After Deploying? Here's How to Fix It
Works locally, white screen in production. The usual causes of a blank page after deploying a React or Vite app — wrong base path, missing environment variables, a JavaScript crash, routing, caching — and how to diagnose each in two minutes with DevTools.
Python Virtual Environments Explained: venv, pip, and uv for Beginners
Why every Python project needs its own virtual environment, how to create and activate one with venv on Windows, Mac and Linux, requirements.txt, the "externally-managed-environment" error, and why many people now use uv instead.