Common errors
Status: 🟩 COMPLETE Last updated: 2026-06-21 Plain-English tagline: A paste-and-find reference for the error messages that actually come up. See the error → find it here → get the fix.
What this is
A reference. You hit an error message you don’t understand. You search this folder for a fragment of the message. You find a plain-English explanation of what went wrong and what fixes it.
This is separate from the gotchas sections in each textbook entry because:
- Errors cut across topics. A “Module not found” can be Next.js, npm, or filesystem case-sensitivity — three sections.
- The fix is short. You don’t want to read 2,000 words to learn that you forgot
npm install. - You arrived because something is broken. Get you unstuck first.
The references
| Reference | What it covers |
|---|---|
| Build errors đźź© | Next.js, ESLint, Vercel deployment errors (TypeScript covered briefly here, depth in dedicated entry) |
| Git errors 🟩 | “fatal: …”, merge conflicts, push rejections, the scary ones |
| Supabase errors 🟩 🟦 | Postgres + Supabase: RLS denials, FK violations, unique-violations, auth/JWT, schema cache, paused projects |
| Browser errors đźź© | CORS, hydration mismatches, mixed content, CSP, chunk-load failures, the React console warnings |
| TypeScript errors 🟩 | Decoding the wall-of-text: “Property X does not exist,” “not assignable,” “possibly null,” generics, overloads |
| Vercel runtime errors 🟩 🟦 | Function timeouts, Edge runtime crashes, 504s, body size limits, region mismatches — runtime not build |
| Node.js errors đźź© | ENOENT, EADDRINUSE, ECONNREFUSED, OOM, unhandled rejections, ESM/CJS conflicts |
| social login errors đźź© | redirect_uri_mismatch, invalid_grant, PKCE failures, the Google/Apple/GitHub-specific gotchas |
| Tailwind surprises đźź© | z-index wars, flex sizing, Tailwind purge, position-fixed-in-transformed-parent, margin collapse |
| CI failures đźź© | GitHub Actions: workflow not running, secrets denied, cache misses, matrix differences, fork-PR restrictions |
| Performance issues đźź© | Slow LCP, big bundles, hydration thrashing, N+1 queries, missing indexes, cold starts, memory leaks |
| AI tools errors 🟩 🟦 | API errors, ChatGPT/Claude/Gemini-specific issues, key safety, output quality, AU-specific gotchas |
The reference now covers the main error classes you’ll hit on the Next.js + Supabase + Vercel stack. Future references land here when genuinely new patterns surface in real work.
How to use this
- Copy a fragment of the error message (the most unique-looking part).
- Search this folder (
Ctrl+Shift+Fin VS Code, scoped toencyclopedia/common-errors/). - Read the explanation and the fix. Each entry is short and action-oriented.
- If the fix doesn’t apply, check the linked textbook entry for the broader context.
What to do when the error isn’t here
Errors evolve. New libraries, new framework versions, new edge cases. If you can’t find your error:
- Read the full message slowly. A lot of errors literally tell you what’s wrong if you read past the scary part.
- Check the textbook entry for the relevant topic. The “Common gotchas” section often covers the same thing.
- Ask Claude in the same project. Claude can read the error, the code, and the project state — better-equipped to diagnose than a generic Google search.
- Save the answer back here if it’s a recurring pattern. The reference grows by accretion.
Future additions (only if patterns surface)
Categories that could grow here when real work surfaces them:
- SAML / OIDC — enterprise auth (beyond OAuth)
- Specific framework upgrades — Next.js major version migrations, React 20+, etc.
- Provider-specific errors — Resend, Sentry, Stripe, others as they enter the stack
These aren’t planned — they’re notes for “if we hit this, here’s where it would go.”
See also
- Git rescue moves 🟩 — the broader “I broke Git” toolkit
- How-to: Debug a Vercel build failure 🟩 — procedural debug walkthrough
- How-to: Rescue a broken Git branch đźź©
- Cheat sheets 🟩 — quick command references