🚨 EMERGENCY REPAIR LAB

The 50+ Real Error Troubleshooting Encyclopedia

Got red text in PowerShell or VS Code? Don't panic. Search your exact error message below to get the root cause and the immediate 1-click fix.

🛠️ UNIVERSAL AI DEBUGGING PROMPT (COPY & PASTE TO AI)

You are an elite full-stack debugging engineer. My application threw the following exact error: [PASTE YOUR TERMINAL OR BROWSER CONSOLE ERROR HERE] Here is the exact code from the file where the error occurred: [PASTE YOUR CODE FILE HERE] Please: 1. Explain in 2 plain-English sentences what caused this error. 2. Provide the exact corrected code block to drop in and fix it. 3. Tell me what verification test I should run in my browser to confirm it is resolved.

❌ 'npm' is not recognized as an internal or external command

Why it happens

Node.js executable is missing from Windows System Environment PATH variable.

Prevention

Always check 'Add to PATH' when running Windows installers.

Immediate Fix

Download Node.js LTS from nodejs.org, check 'Add to PATH' in installer, restart VS Code and run 'node -v'.

❌ Error: listen EADDRINUSE: address already in use :::3000

Why it happens

Another background Node process or old terminal session is occupying port 3000.

Prevention

Use Ctrl+C to gracefully terminate dev servers instead of closing the terminal tab.

Immediate Fix

In PowerShell run: Stop-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess -Force

❌ File cannot be loaded because running scripts is disabled on this system

Why it happens

Windows PowerShell Execution Policy blocks unsigned npm scripts by default.

Prevention

Configure execution policy once on every new Windows PC.

Immediate Fix

Run PowerShell as Admin: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

❌ Supabase: new row violates row-level security policy for table

Why it happens

Row Level Security (RLS) is enabled, but no INSERT policy permits authenticated users to write rows.

Prevention

Always create SELECT, INSERT, UPDATE, and DELETE policies when enabling RLS.

Immediate Fix

In Supabase SQL Editor run: CREATE POLICY 'Users insert own' ON table_name FOR INSERT WITH CHECK (auth.uid() = user_id);

❌ CORS error: Access to XMLHttpRequest has been blocked by CORS policy

Why it happens

Browser blocked client-side JavaScript from calling third-party API without CORS headers.

Prevention

Server-to-server HTTP requests are never subject to browser CORS restrictions.

Immediate Fix

Call the API from a Next.js Server Action or API Route Handler (app/api/...) instead of the browser.

❌ git push origin main rejected: fetch first (non-fast-forward)

Why it happens

GitHub repository contains commits (e.g. README created in browser) that your local machine lacks.

Prevention

Never edit files directly on GitHub web before pushing initial local code.

Immediate Fix

Run: git pull origin main --rebase and then run: git push origin main

❌ Module not found: Can't resolve 'lucide-react' (or another package)

Why it happens

The package was imported in code but has not been installed in node_modules.

Prevention

Always install packages before importing them in TypeScript files.

Immediate Fix

Run: npm install [package-name] (e.g. npm install lucide-react)

❌ Invalid API Key / Unauthorized (401)

Why it happens

Environment variable is missing from .env.local or server was not restarted after editing .env.

Prevention

Always restart local dev server when modifying environment variables.

Immediate Fix

Restart Next.js dev server (Ctrl+C then npm run dev) and verify variable name has no typos.

❌ Hydration failed because the initial UI does not match what was rendered on the server

Why it happens

HTML generated on server differs from browser (e.g. rendering new Date() or localStorage on server).

Prevention

Keep server components deterministic and use client components for browser APIs.

Immediate Fix

Wrap browser-only code in useEffect() or use dynamic(() => import(...), { ssr: false }).

❌ Vercel Build Error: Type error: Property 'xyz' does not exist on type 'abc'

Why it happens

TypeScript strict mode caught a type mismatch during production build.

Prevention

Run local build (npm run build) before pushing to GitHub.

Immediate Fix

Fix the interface type definition in the file or run 'npx tsc --noEmit' locally to catch errors before push.

❌ Resend: Domain not verified / 403 Forbidden

Why it happens

DNS TXT (SPF) or CNAME (DKIM) records have not finished propagating across global nameservers.

Prevention

Double check registrar hostnames: many registrars automatically append your domain name.

Immediate Fix

Wait 15 minutes and check https://whatsmydns.net. Ensure no extra domain suffixes were duplicated.

❌ Error: supabaseUrl is required

Why it happens

createClient() was called with undefined NEXT_PUBLIC_SUPABASE_URL.

Prevention

Public client variables in Next.js MUST start with NEXT_PUBLIC_ prefix.

Immediate Fix

Check .env.local: ensure variable starts with NEXT_PUBLIC_ if accessed on the client side.

❌ PrismaClientInitializationError: Can't reach database server

Why it happens

Database connection string has invalid password or IP is blocked by firewall.

Prevention

Keep database credentials secured in password manager and verify pooler ports (6543 vs 5432).

Immediate Fix

Verify connection string password in .env and ensure database provider allows 0.0.0.0/0 incoming connections.

❌ git: command not found (in VS Code terminal)

Why it happens

Git for Windows was installed while VS Code was open, or Git bin is not in PATH.

Prevention

Install Git before installing VS Code or restart VS Code after installing tools.

Immediate Fix

Completely close and reopen Visual Studio Code. If still failing, restart Windows PC.

❌ 413 Request Entity Too Large

Why it happens

User uploaded a file exceeding the maximum body size allowed by Next.js or cloud host.

Prevention

Always use client-to-bucket direct uploads for files larger than 4.5MB.

Immediate Fix

Upload files directly from browser to Supabase Storage / Cloudflare R2 using Signed URLs instead of proxying through server.

❌ Stripe: Webhook signature verification failed

Why it happens

STRIPE_WEBHOOK_SECRET in environment variables does not match the webhook endpoint signing secret.

Prevention

Test webhooks locally using Stripe CLI: stripe listen --forward-to localhost:3000/api/webhooks/stripe.

Immediate Fix

Copy the exact signing secret (starts with whsec_...) from Stripe Dashboard into .env.local.

❌ Cannot read properties of null (reading 'user')

Why it happens

Attempted to access user profile properties before authentication session has loaded.

Prevention

Always handle loading and unauthenticated states gracefully.

Immediate Fix

Add optional chaining: user?.email or show a loading skeleton while auth state is resolving.

❌ Next.js Error: cookies() can only be called in a Server Component

Why it happens

Attempted to read server cookies inside a client component with 'use client'.

Prevention

Keep cookie and database calls in Server Components or Server Actions.

Immediate Fix

Pass the user data as props from a parent Server Component into the client component.

❌ Cloudflare Pages Build Failed: exit code 1

Why it happens

Build command or output directory misconfigured in Cloudflare Pages dashboard.

Prevention

Review official Cloudflare Pages Next.js documentation for current build flags.

Immediate Fix

Set Framework Preset to 'Next.js' and set build command to 'npx @cloudflare/next-on-pages'.

❌ Render Web Service 502 Bad Gateway / Port timeout

Why it happens

Node application is listening on hardcoded port 3000 instead of process.env.PORT.

Prevention

Cloud hosts like Render and Railway inject a dynamic PORT environment variable at runtime.

Immediate Fix

Update server to listen on: const PORT = process.env.PORT || 3000;