Debugging
Finding out why something broke: reading errors, browser dev tools, logs, and the classic works-locally-fails-in-production gap.
56 posts · page 1 of 2
"Your Connection Is Not Private" on Your Own Site: Causes and Fixes
When visitors see NET::ERR_CERT_DATE_INVALID, ERR_CERT_COMMON_NAME_INVALID or ERR_CERT_AUTHORITY_INVALID on your site, the SSL certificate is expired, for the wrong name, or incomplete. How to tell which, and how to fix each one.
"Unexpected Token < in JSON at Position 0": What It Means and How to Fix It
Your code expected JSON and got HTML — almost always an error page or your app's index.html. Why it happens (wrong URL, 404, server error, SPA fallback, login redirect), how to see what the server actually sent, and how to parse responses safely.
How to Test Webhooks Locally: Stripe CLI, Tunnels, and Replays
Webhook providers can't reach localhost, so local testing needs a forwarder or a tunnel. How to use provider CLIs like stripe listen, general tunnels like ngrok and Cloudflare Tunnel, request-capture tools, and fixture replays in automated tests — plus the signature-verification gotchas.
"Each Child in a List Should Have a Unique Key Prop": What It Means
React's key warning appears when you render a list without telling React which item is which. Why keys matter, why array index is a bad key for lists that change, what to use instead, and how to fix the warning in fragments and nested maps.
React "Too Many Re-renders" and "Maximum Update Depth Exceeded": Fixes
Both errors mean a component keeps updating state, which re-renders it, which updates state again — forever. The four patterns that cause it (calling a handler instead of passing it, setState during render, effects without dependencies, objects in dependency arrays) and their fixes.
Playwright Tutorial: End-to-End Tests That Aren't Flaky
Playwright drives real browsers to test your app the way users use it. Install it, write your first test, use role-based locators and auto-waiting assertions, log in once and reuse the session, run against a dev server, debug with UI mode and traces, and run it in CI.
"Command Not Found": The PATH Variable Explained
"command not found" or "is not recognized as an internal or external command" usually means the program is installed but your terminal doesn't know where to look. How PATH works on Mac, Linux and Windows, how to check it, and how to add a folder permanently.
"No Space Left on Device": Finding and Freeing Disk Space on a Server
When a server's disk fills up, databases stop writing, deploys fail and apps crash with ENOSPC. How to find what's using space with df and du, the usual culprits (logs, Docker, journald, old releases, deleted-but-open files), inode exhaustion, and how to stop it happening again.
"TypeError: X Is Not a Function": The Common Causes and Fixes
"is not a function" means you tried to call something that isn't a function — usually undefined, an object, or the wrong kind of value. The usual suspects: .map on a non-array, wrong import, missing await, a typo, or a name collision. How to diagnose each.
Git Push Rejected: "Updates Were Rejected Because the Remote Contains Work"
git push fails with "rejected — fetch first" or "non-fast-forward" when GitHub has commits you don't. How to pull and combine them safely, when force-pushing is fine and when it destroys work, and the other rejection messages: protected branches, large files, and secrets.
"Permission Denied (publickey)" on GitHub: How to Fix It
GitHub rejected your SSH key — either you don't have one, it isn't added to GitHub, your SSH agent isn't offering it, or you're using the wrong account. A step-by-step fix with ssh -T, plus the HTTPS alternative and the 'Support for password authentication was removed' error.
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.
"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.
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.
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.
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.
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.
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.
Reading Postgres EXPLAIN ANALYZE: A Practical Guide to Query Plans
How to read a Postgres query plan: EXPLAIN vs EXPLAIN ANALYZE, BUFFERS, costs vs actual times, loops, scan and join types, spotting bad row estimates, sorts spilling to disk — plus pg_stat_statements and auto_explain for finding the queries worth fixing.
Postgres "Deadlock Detected": Why It Happens and How to Prevent It
ERROR: deadlock detected. How Postgres deadlocks happen, how to read the log detail, the common causes — inconsistent lock ordering, batch updates, foreign keys, upserts — and the fixes: consistent ordering, shorter transactions, explicit locking, and safe retries.