Skip to main content

​
Common Issues

Running into problems? You’re not alone. Here are the most common issues and how to fix them.
Problem: Error like “The engine ‘node’ is incompatible with this module”Solution:This playground requires Node.js 18 or higher. Check your version:
node --version
If you see anything lower than v18.0.0, you need to update Node.js:
  1. Visit nodejs.org
  2. Download the LTS (Long Term Support) version
  3. Install it
  4. Restart your terminal
  5. Verify with node --version again
Alternative: Use nvm to manage Node versions:
nvm install 18
nvm use 18
Problem: npm install takes forever, fails, or shows errorsSolutions to try:1. Clear npm cache:
npm cache clean --force
2. Delete node_modules and package-lock.json:
rm -rf node_modules package-lock.json
npm install
3. Try yarn instead:
npm install -g yarn
yarn install
4. Check your internet connection:
  • npm needs to download packages from the internet
  • Corporate firewalls can sometimes block npm
  • Try using your phone’s hotspot if you suspect network issues
5. Use a different npm registry:
npm config set registry https://registry.npmjs.org/
Problem: Error: “Port 3000 is already in use”What’s happening: Another app is already running on port 3000Solution 1 - Find and kill the process:On Mac/Linux:
lsof -ti:3000 | xargs kill -9
On Windows:
netstat -ano | findstr :3000
taskkill /PID <PID_NUMBER> /F
Solution 2 - Use a different port:
npm run dev -- -p 3001
Then open http://localhost:3001
Problem: Changes to code don’t show up in the browser automaticallySolutions:1. Hard refresh the browser:
  • Mac: Cmd + Shift + R
  • Windows/Linux: Ctrl + Shift + R
2. Restart the dev server:
  • Press Ctrl + C in the terminal to stop it
  • Run npm run dev again
3. Check file watchers (Linux):Linux has a limit on file watchers. Increase it:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
4. Clear Next.js cache:
rm -rf .next
npm run dev
5. Disable browser extensions:
  • Some ad blockers or extensions can interfere
  • Try opening in incognito/private mode
Problem: Error like “Cannot find module ‘react’” or similarSolutions:1. Install dependencies:
npm install
2. Check you’re in the right directory:
pwd  # Shows current directory
ls   # Should show package.json
Make sure you’re inside a lesson folder (like 01-hello-saas), not the root.3. Reinstall everything:
rm -rf node_modules package-lock.json
npm install
4. Check for typos in imports:
// Wrong
import { Button } from './componets/Button'  // typo!

// Right
import { Button } from './components/Button'
Problem: Tailwind classes aren’t applying stylesSolutions:1. Check tailwind.config.js:Make sure content paths are correct:
content: [
  './app/**/*.{js,ts,jsx,tsx,mdx}',
  './components/**/*.{js,ts,jsx,tsx,mdx}',
]
2. Import Tailwind in globals.css:
@tailwind base;
@tailwind components;
@tailwind utilities;
3. Restart dev server:
# Stop with Ctrl+C, then:
npm run dev
4. Check for typos in class names:
// Wrong
className="bg-blue-500"  // class name is misspelled

// Right
className="bg-blue-500"
Problem: Error about using hooks or events in Server ComponentsWhat’s happening: You’re trying to use client-side features (like useState, onClick) in a Server ComponentSolution: Add 'use client' at the top of the file:
'use client'

import { useState } from 'react'

export default function MyComponent() {
  const [count, setCount] = useState(0)
  // ... rest of component
}
When you need ‘use client’:
  • Using React hooks (useState, useEffect, etc.)
  • Adding event handlers (onClick, onChange, etc.)
  • Using browser APIs (window, localStorage, etc.)
  • Using client-side libraries
Problem: Can’t connect to MongoDB or database errorsSolutions:1. Check your .env.local file:Make sure it exists and has the correct MongoDB URI:
MONGODB_URI=mongodb+srv://username:[email protected]/dbname
2. Verify MongoDB credentials:
  • Check username and password are correct
  • No special characters that need URL encoding
  • Database name is correct
3. Whitelist your IP address:In MongoDB Atlas:
  1. Go to Network Access
  2. Add your current IP address
  3. Or add 0.0.0.0/0 to allow all (development only!)
4. Restart dev server after changing .env:
# Stop with Ctrl+C, then:
npm run dev
Environment variables are loaded at startup.
Problem: Stripe checkout or webhooks not workingSolutions:1. Check environment variables:Make sure these are in .env.local:
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
2. Use Stripe test mode:Make sure you’re using test keys (they start with pk_test_ and sk_test_), not live keys.3. Test webhook locally:Use Stripe CLI to forward webhooks:
stripe listen --forward-to localhost:3000/api/webhook
4. Check webhook endpoint:Make sure your webhook route is configured correctly in app/api/webhook/route.js
Problem: App works locally but fails on VercelSolutions:1. Check environment variables:Make sure all .env.local variables are added in Vercel dashboard:
  1. Go to Project Settings
  2. Click Environment Variables
  3. Add each variable
2. Check build logs:Vercel shows detailed error messages. Common issues:
  • Missing dependencies
  • Type errors
  • Environment variable issues
3. Verify Node.js version:In package.json, specify the Node version:
"engines": {
  "node": ">=18.0.0"
}
4. Clear Vercel cache:In your deployment settings, try “Redeploy” and check “Clear cache”.
Problem: Code works but shows errors in editorSolutions:1. Install dependencies:
npm install
2. Restart your editor:VS Code and other editors sometimes need a restart to pick up changes.3. Disable for a line (if needed):
// eslint-disable-next-line
const something = possiblyUndefined
But try to fix the actual issue first!

​
Still Stuck?

If none of these solutions work:
  1. Copy the exact error message and search Google
  2. Check Stack Overflow - search for your error
  3. Ask AI tools (ChatGPT, Claude) - paste your error and code
  4. Join the community - other learners might have solved it
  5. Check GitHub issues - see if it’s a known issue
When asking for help, always include:
  • The exact error message
  • What you were trying to do
  • What you’ve already tried
  • Your Node.js version (node --version)

​
Prevention Tips

Before you start coding:
  • Make sure you’re in the right directory
  • Run npm install first
  • Check that the dev server is running
  • Open the right URL (usually http://localhost:3000)
While coding:
  • Save files before checking the browser
  • Check the terminal for error messages
  • Read error messages carefully - they’re helpful!
  • Test small changes frequently
When something breaks:
  • Don’t panic - errors are normal
  • Read the error message
  • Check what you changed last
  • Use git to revert if needed
Happy troubleshooting!

Build docs developers (and LLMs) love

Get started for freeTalk to us