Debugging
Finding out why something broke: reading errors, browser dev tools, logs, and the classic works-locally-fails-in-production gap.
130 posts · page 2 of 5
"ReferenceError: window is not defined" in Next.js: How to Fix It
window, document and localStorage only exist in the browser. Next.js renders components on the server first, where they don't exist. Why it happens, and the fixes: useEffect, 'use client', typeof checks, dynamic imports with ssr: false, and libraries that touch window on import.
What Is OpenTelemetry? Traces, Metrics and Logs Explained
OpenTelemetry is the open standard for collecting traces, metrics and logs from your app and sending them to any observability backend. The three signals, spans and context propagation, auto-instrumenting a Node.js app, the Collector, backends, LLM and agent tracing, and what a small team actually needs.
What Is ngrok? Share Your Localhost With the Internet
ngrok gives your local app a public HTTPS URL by tunnelling traffic to your machine. What it's for (webhooks, demos, mobile testing), how to use it, the request inspector, free vs paid limits, security cautions, and alternatives like Cloudflare Tunnel.
What Is curl? A Beginner's Guide With Practical Examples
curl is a command-line tool for making web requests, installed on almost every computer. The commands you'll actually use — GET, POST JSON, headers, authentication, following redirects, downloading files, seeing response headers — and how to read API docs that use it.
"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.
"A Component Is Changing an Uncontrolled Input to Be Controlled": Fix
React warns when an input's value starts as undefined and later becomes a string. What controlled and uncontrolled inputs are, why undefined initial state causes this, and the fixes: initialise with '', use ?? '' for loaded data, and handle checkboxes and selects properly.
TypeScript "Type X Is Not Assignable to Type Y": How to Read and Fix It
TypeScript's most common error means a value doesn't match the type expected where you put it. How to read the message (including long nested ones), the common cases — string vs number, null and undefined, string literals, missing object properties, array types — and fixes that don't just hide the bug.
"This Site Can't Be Reached": What the Error Code Tells You
Chrome's 'This site can't be reached' covers several different problems, and the small error code underneath tells you which: NXDOMAIN, CONNECTION_REFUSED, TIMED_OUT, CONNECTION_RESET and more. What each means and how to fix it, as a visitor and as a site owner.
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.
"error: src refspec main does not match any": How to Fix It
Git can't push a branch called main because it doesn't exist locally — usually because there are no commits yet or the branch is called master. How to check which it is and fix it in one or two commands.
"fatal: refusing to merge unrelated histories": How to Fix It
Git refuses to merge two branches that share no common commit — usually because you created a repo locally and another on GitHub with a README. Why it happens, the --allow-unrelated-histories fix, resolving the resulting conflicts, and how to avoid it.
"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.
React Error Boundaries: Stop One Broken Component Crashing the Page
Without an error boundary, one component throwing during render blanks your entire React app. How error boundaries work, using react-error-boundary with fallbacks and reset, Next.js error.tsx and global-error.tsx, what boundaries don't catch, and reporting errors to monitoring.
Python "ModuleNotFoundError: No module named ...": How to Fix It
Python can't find a module you imported. Usually the package isn't installed in the environment you're running, you installed it into a different Python, the package name differs from the import name, or it's your own module and the path is wrong. How to check and fix each.
TypeScript "Property Does Not Exist on Type": Causes and Fixes
TypeScript says the property you're reading isn't part of the type. The common causes — a typo or hallucinated field, a missing field in your type, union types that need narrowing, unknown/{} types, window and process.env, DOM elements typed too broadly, and catch errors — with proper fixes.
Postgres Timeouts: statement_timeout, lock_timeout and Friends
Postgres ships with every timeout disabled, so a stuck query or forgotten transaction can hold locks forever. What statement_timeout, lock_timeout, idle_in_transaction_session_timeout, transaction_timeout and idle_session_timeout do, the lock-queue outage they prevent, safe values, and where to set them.
Postgres "ERROR: relation does not exist": Causes and Fixes
Postgres can't find the table you named. The usual causes — migrations not run, connected to the wrong database, uppercase names and double quotes, the table is in a different schema, or permissions — and how to check each with psql.
Postgres Planner Statistics: Why the Query Plan Is Wrong
Postgres picks query plans from statistics about your data. When they're stale or too coarse, row estimates are off by orders of magnitude and the planner chooses a terrible plan. How ANALYZE samples tables, reading pg_stats, default_statistics_target, correlated columns and CREATE STATISTICS, and fixing misestimates.
Postgres "password authentication failed for user": How to Fix It
Postgres rejected the username or password your app sent. The real causes — wrong password in the connection string, special characters not URL-encoded, a Docker volume that kept an old password, the wrong user or host, pg_hba.conf rules — and how to reset the password safely.
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.
Playwright MCP: Let Claude Code Use a Real Browser
The Playwright MCP server lets AI tools open pages, click, type and read a live browser through accessibility snapshots instead of screenshots. How to add it to Claude Code, useful prompts for testing and debugging, key options like headless and isolated, and its limits.
pip "error: externally-managed-environment": What It Means and How to Fix It
Newer Linux distributions and Homebrew stop pip from installing packages into the system Python, to protect the operating system. Why it happens, and the right fixes: a virtual environment, uv, or pipx for tools — and why --break-system-packages is a last resort.
pg_stat_statements: Find the Queries Slowing Down Your Postgres
pg_stat_statements records statistics for every distinct query your database runs — calls, total and mean time, rows, cache hits. How to enable it, the queries to find what costs the most, interpreting the results, resetting, and turning findings into indexes and fixes.