Next.js Fullstack Training
Chapter 8
Troubleshooting
8.1 Dev Server
| Symptom | Fix |
|---|---|
| pnpm dev fails — "port 3000 in use" | lsof -ti:3000 | xargs kill then re-run pnpm dev |
| "Module not found" after pulling changes | pnpm install — a teammate added a new dependency |
| "Cannot find module '@/...'" | Check tsconfig.json paths — @/* must map to ./src/* |
| Changes not reflected on reload | Hard refresh Cmd+Shift+R. If still wrong, stop/start pnpm dev |
| Turbopack error with no useful message | Try pnpm dev --no-turbopack temporarily for a clearer error |
8.2 TypeScript Errors
| Error | What it means + Fix |
|---|---|
| Property does not exist on type | Your type is missing a field. Check the interface or Drizzle schema. |
| Type X is not assignable to type Y | Type mismatch. Check what the function expects vs what you're passing. |
| Object is possibly undefined | Add null check: if (!value) return; or use optional chain: value?.property |
| params accessed as object not Promise | Use await params — see Next.js 16 breaking change in Chapter 5.3 |
| useActionState is not a function | Import from "react" not "react-dom". useFormStatus is from react-dom. |
8.3 Database / Drizzle
| Error | Fix |
|---|---|
| Connection refused / ECONNREFUSED | Check DATABASE_URL is correctly set in .env.local |
| "relation does not exist" | Run: pnpm db:migrate |
| Cannot insert — not-null constraint | Missing a required field. Check the schema. |
| Schema changes not in DB after edit | Run: pnpm db:generate && pnpm db:migrate |
| Type error on Drizzle result | Use db.query.tableName.findMany({ with:{} }) for relational typing |
8.4 Server Actions
| Error | Fix |
|---|---|
| "Server Actions must be async" | Add async keyword: export async function myAction() |
| Action runs on client | Missing "use server" at the top of the file |
| formData.get() returns null | Check input's name= attribute matches the key you're reading |
| revalidatePath does nothing | Path must exactly match the route: /board not /board/ |
| Action works locally but fails in production | Check env vars are set in Vercel dashboard |
Common Mistake
The nuclear option — if nothing works:
1. rm -rf node_modules .next
2. pnpm install
3. pnpm dev
This fixes ~30% of mysterious errors.