Common Errors

A comprehensive guide to errors you'll encounter and how to fix them. Keep this page bookmarked for quick reference!

Build Errors

Error: "Module not found"

You see:

Module not found: Can't resolve '@/components/Header'

Cause: File doesn't exist or path is wrong

Fix:

1. Check file exists at that path
2. Verify spelling (case-sensitive!)
3. Check import path is correct

// ❌ Wrong
import Header from '@/components/header' // lowercase

// ✅ Correct
import Header from '@/components/layout/Header'

Error: "Unexpected token"

You see:

Unexpected token, expected ","

Cause: Syntax error (missing bracket, comma, etc.)

Common fixes:

• Missing closing tag: <div> needs </div>
• Missing comma in object/array
• Missing closing bracket } or )

How to find:

• Look at line number in error
• Check for unclosed tags/brackets above that line

Error: "Cannot find module"

You see:

Cannot find module 'react-icons'

Cause: Package not installed

Fix:

npm install react-icons

Then restart dev server.

Error: "Port 3000 is already in use"

You see:

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

Cause: Dev server already running

Fix:

1. Find and close other terminal running npm run dev
2. Or kill the process:

# Mac/Linux
lsof -ti:3000 | xargs kill

# Windows
netstat -ano | findstr :3000
# Note the PID, then:
taskkill /PID <pid> /F

React Errors

Error: "Each child should have a unique key prop"

You see:

Warning: Each child in a list should have a unique "key" prop

Cause: Missing key in mapped elements

Fix:

// ❌ Wrong
{items.map((item) => (
  <div>{item.name}</div>
))}

// ✅ Correct
{items.map((item) => (
  <div key={item.id}>{item.name}</div>
))}

Error: "Cannot read property 'X' of undefined"

You see:

TypeError: Cannot read property 'name' of undefined

Cause: Trying to access property on undefined/null

Fix with optional chaining:

// ❌ Wrong
<p>{user.name}</p>

// ✅ Correct
<p>{user?.name}</p>

Or check if exists:

{user && <p>{user.name}</p>}

Error: "Hydration failed"

You see:

Error: Hydration failed because the initial UI does not match

Cause: Server-rendered HTML differs from client

Common causes:

• Using window or document in server component
• Random values (Math.random(), Date.now()) in render
• Conditional rendering based on browser state

Fix:

// ❌ Wrong (in Server Component)
const id = Math.random()

// ✅ Correct (use Client Component)
"use client"
const [id, setId] = useState(() => Math.random())

TypeScript Errors

Error: "Type 'X' is not assignable to type 'Y'"

You see:

Type 'string' is not assignable to type 'number'

Fix: Match the types

// ❌ Wrong
const age: number = "25"

// ✅ Correct
const age: number = 25

Error: "Property 'X' does not exist on type 'Y'"

You see:

Property 'email' does not exist on type 'User'

Cause: Interface missing property

Fix: Add to interface

interface User {
  name: string
  email: string  // Add missing property
}

Error: "Object is possibly 'undefined'"

You see:

Object is possibly 'undefined'

Fix with optional chaining:

// ❌ Wrong
user.name

// ✅ Correct
user?.name

// Or check first
if (user) {
  user.name
}

Git Errors

Error: "Your local changes would be overwritten"

You see:

error: Your local changes to the following files would be overwritten by checkout

Cause: Uncommitted changes

Fix: Commit or stash first

# Option 1: Commit
git add .
git commit -m "Save work"

# Option 2: Stash (temporary save)
git stash
git checkout other-branch
git stash pop  # Get changes back

Error: "fatal: not a git repository"

You see:

fatal: not a git repository (or any of the parent directories): .git

Cause: Not in project directory or not initialized

Fix:

# Navigate to project
cd /path/to/k12worx-jamboree

# Or initialize (if new project)
git init

Error: "Please commit your changes or stash them"

Cause: Can't switch branches with uncommitted changes

Fix: Same as "overwritten" error above

Error: "Merge conflict"

You see:

CONFLICT (content): Merge conflict in app/page.tsx

Fix:

1. Open conflicted file
2. Look for conflict markers:

<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> main

3. Edit to keep what you want
4. Remove conflict markers
5. Save, add, and commit:

git add app/page.tsx
git commit -m "Resolve merge conflict"

npm Errors

Error: "npm ERR! code ENOENT"

You see:

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path package.json

Cause: Not in project directory

Fix:

# Navigate to website folder
cd website
npm install

Error: "ERESOLVE unable to resolve dependency tree"

Cause: Package version conflicts

Fix:

# Try legacy peer deps
npm install --legacy-peer-deps

# Or force
npm install --force

Error: "Permission denied"

Cause: Missing permissions (usually on Mac/Linux)

Fix:

# DON'T use sudo with npm!
# Instead, fix permissions:
sudo chown -R $USER ~/.npm

Browser Errors

Error: "Failed to fetch"

In browser console:

Failed to fetch

Cause: API request failed

Check:

1. Is dev server running?
2. Is API endpoint correct?
3. Check Network tab in DevTools
4. Look for CORS errors

Error: "Uncaught ReferenceError: X is not defined"

Cause: Using undefined variable

Fix:

// ❌ Wrong
console.log(userName)  // userName not defined

// ✅ Correct
const userName = "Alice"
console.log(userName)

Error: "Maximum update depth exceeded"

Cause: Infinite loop in useEffect or setState

Fix:

// ❌ Wrong (causes infinite loop)
useEffect(() => {
  setState(state + 1)  // Runs every render!
})

// ✅ Correct (runs once)
useEffect(() => {
  setState(1)
}, [])  // Empty dependency array

CSS/Styling Errors

Error: "Class does not exist"

Tailwind error:

The 'bg-primary' class does not exist

Cause: Custom color not defined

Fix: Add to tailwind.config.ts

theme: {
  extend: {
    colors: {
      primary: '#3b82f6',
    },
  },
},

Layout broken after change

Cause: Removed important class or broke structure

Fix:

1. Use Cmd+Z to undo
2. Check browser DevTools (inspect element)
3. Look for missing flex/grid classes
4. Verify closing tags

Quick Fixes

Clear Everything and Start Fresh

When nothing works:

# Stop dev server (Ctrl+C)

# Delete node_modules and cache
rm -rf node_modules .next

# Reinstall
npm install

# Restart
npm run dev

Hard Refresh Browser

Clear browser cache:

• Mac: Cmd + Shift + R
• Windows: Ctrl + Shift + R

Check Git Status

See what changed:

git status
git diff

Reset to Last Commit

Undo all changes:

# See changes first
git status

# Reset everything (WARNING: loses changes!)
git reset --hard HEAD

Error-Reading Checklist

When you see an error:

1. Read the full message - Don't just see "Error"
2. Note the file and line number
3. Look at the actual line mentioned
4. Check lines above it (often the real error is earlier)
5. Google the error (someone else had this problem!)
6. Check your recent changes (what did you edit last?)

Prevention Tips

1. Save Often

File not saved = changes not applied

2. One Change at a Time

If something breaks, you know what caused it.

3. Test After Each Change

Don't make 10 changes then test.

4. Read Error Messages

They usually tell you exactly what's wrong!

5. Check Console

Open browser DevTools console regularly.

What's Next

Now that you know common errors, let's learn debugging techniques:

Debugging Tips →

---

Quick Links

• ← Chapter 09 Overview
• Debugging Tips →