Error: This package requires Node.js version 18 or higher
The current version of Node.js is v16.14.0

# Check current version
node --version

# Install Node.js 18+ using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# Or download from nodejs.org
# https://nodejs.org/

# Verify installation
node --version  # Should show v18+

pnpm: command not found

# Install pnpm globally
npm install -g pnpm

# Alternative: using corepack (Node.js 16+)
corepack enable
corepack prepare pnpm@latest --activate

# Verify installation
pnpm --version

EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

# Don't use sudo! Fix npm permissions instead
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH=~/.npm-global/bin:$PATH

# Or use Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Error: Connection terminated unexpectedly
Error: password authentication failed for user "postgres"

# Correct format
DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require"

# Common format errors:
❌ Missing password: postgresql://username@host/database
❌ Wrong port: postgresql://username:password@host:5433/database
❌ Missing sslmode for cloud databases

# For local PostgreSQL
brew services start postgresql@15  # macOS
sudo systemctl start postgresql    # Linux

# For cloud databases, check:
# - Database is running in provider dashboard
# - IP whitelist includes your IP
# - SSL/TLS settings match connection string

# Test with psql
psql "$DATABASE_URL"

# Or check via debug panel
curl http://localhost:3000/debug

Error: relation "users" already exists
Error: column "new_column" already exists

# Reset database (CAUTION: Deletes all data)
pnpm db:reset

# Or use migrations for production
pnpm db:generate  # Generate migration files
pnpm db:migrate   # Apply migrations

# Force schema sync (development only)
pnpm db:push --force

Cannot connect to database
Error: Failed to start Drizzle Studio

# Check if port 4983 is available
lsof -ti:4983 | xargs kill

# Restart Drizzle Studio
pnpm db:studio

# Check environment variables
echo $DATABASE_URL  # Should not be empty

# Verify database connection first
pnpm db:push

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

# Find and kill process using port 3000
lsof -ti:3000 | xargs kill

# Or find the specific process
lsof -i :3000

# Use different port
PORT=3001 pnpm dev

# Kill all Next.js processes
pkill -f "next dev"

# 1. Clear Next.js cache
rm -rf .next/
pnpm dev

# 2. Clear all caches
pnpm clean
pnpm install
pnpm dev

# 3. Check file watching limits (Linux)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 4. Disable browser cache
# Open DevTools → Network → Check "Disable cache"

Error: Module not found
Error: Cannot resolve module

# Clear all caches
rm -rf .next/
rm -rf node_modules/.cache/
rm -rf apps/web/.turbo/

# Reinstall dependencies
pnpm install

# Rebuild shared packages
pnpm build:packages

# Full reset
pnpm clean
pnpm install
pnpm dev

Cannot find module '@/components/Button' or its corresponding type declarations
Cannot find module '@packages/ui' or its corresponding type declarations

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./apps/web/*"],
      "@packages/ui": ["./packages/ui/src"],
      "@packages/utils": ["./packages/utils/src"],
      "@packages/database": ["./packages/database/src"]
    }
  }
}

# TypeScript needs compiled packages for type checking
pnpm build:packages

# Then run type checking
pnpm type-check

# In VS Code: Cmd/Ctrl + Shift + P
# Type: "TypeScript: Restart TS Server"

# Or restart your editor

Property 'user' does not exist on type 'Session'
Type 'string | undefined' is not assignable to type 'string'

# 1. Check type definitions
cat packages/database/src/schema/index.ts
cat lib/types/auth.types.ts

# 2. Regenerate types after schema changes
pnpm db:push
pnpm build:packages

# 3. Clear TypeScript cache
rm -rf node_modules/.cache/
rm tsconfig.tsbuildinfo
pnpm type-check

Error: Build failed because of TypeScript errors
Cannot find module or its corresponding type declarations

# Always rebuild packages before type checking
pnpm build:packages
pnpm type-check

# Or use the comprehensive CI command
pnpm ci

# 1. Check Tailwind config
cat tailwind.config.ts

# 2. Verify content paths include your files
content: [
  "./pages/**/*.{js,ts,jsx,tsx,mdx}",
  "./components/**/*.{js,ts,jsx,tsx,mdx}",
  "./app/**/*.{js,ts,jsx,tsx,mdx}",
  "./packages/ui/src/**/*.{js,ts,jsx,tsx}",
],

# 3. Restart dev server
pnpm dev

# 4. Clear CSS cache
rm -rf .next/
pnpm dev

Error: Cannot find module './ui/button'
Component is not rendering correctly

# 1. Check if component is installed
ls components/ui/

# 2. Add missing components
pnpm ui add button
pnpm ui add card input

# 3. Check component imports
# Should be: import { Button } from "@/components/ui/button"
# Not: import { Button } from "@packages/ui"

# 4. Update existing components
pnpm ui update

# 1. Check file naming (.module.css)
components/Header.module.css  # ✅ Correct
components/header.css         # ❌ Won't work as module

# 2. Check import syntax
import styles from './Header.module.css';  # ✅ Correct
import './Header.css';                     # ❌ Global styles

# 3. Restart development server
pnpm dev

Error: expo command not found
Metro bundler error

# 1. Install Expo CLI globally
npm install -g @expo/cli

# 2. Clear Metro cache
pnpm --filter mobile expo start --clear

# 3. Reset Metro bundler
rm -rf apps/mobile/node_modules/.cache/
pnpm --filter mobile install

# 4. Check mobile app setup
cd apps/mobile
ls app.config.js  # Should exist

# 1. Check network connectivity
# Ensure device and computer on same network

# 2. Check firewall settings
# Allow connections to port 8081 (Metro) and 19000 (Expo)

# 3. Use tunnel mode (slower but more reliable)
pnpm --filter mobile expo start --tunnel

# 4. Check IP address
ifconfig | grep inet  # macOS/Linux
ipconfig              # Windows

# 1. Use changed-files-only commands during development
pnpm lint:changed      # Instead of pnpm lint
pnpm type-check:changed # Instead of pnpm type-check

# 2. Clear caches
pnpm clean
pnpm install

# 3. Check system resources
top    # CPU usage
free   # Memory usage (Linux)
df -h  # Disk space

# 4. Optimize build
# Ensure .gitignore includes build artifacts
echo ".next/" >> .gitignore
echo "dist/" >> .gitignore

JavaScript heap out of memory
Error: Cannot allocate memory

# 1. Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" pnpm build

# 2. Close unnecessary applications
# Check Activity Monitor (macOS) or Task Manager (Windows)

# 3. Use changed-files-only commands
pnpm lint:changed
pnpm type-check:changed

# 4. Split large files
# Break down large components into smaller ones

404 - Not Found
500 - Internal Server Error

# 1. Check API route file structure
app/api/users/route.ts      # ✅ Correct
app/api/users.ts            # ❌ Wrong location
pages/api/users.ts          # ❌ Old Pages Router

# 2. Check HTTP method exports
export async function GET(request: NextRequest) { ... }
export async function POST(request: NextRequest) { ... }

# 3. Test API directly
curl http://localhost:3000/api/users
curl -X POST http://localhost:3000/api/users -d '{"name":"test"}'

# 4. Check server logs
pnpm dev  # Check terminal for error messages

Access to fetch at 'api/users' from origin 'http://localhost:3000' has been blocked by CORS policy

# 1. Use relative URLs for same-origin requests
fetch('/api/users')  # ✅ Correct
fetch('http://localhost:3000/api/users')  # ❌ Unnecessary

# 2. For external APIs, configure CORS in API route
export async function GET() {
  const response = NextResponse.json({ data });
  response.headers.set('Access-Control-Allow-Origin', '*');
  return response;
}

# 3. Use Next.js rewrites for external APIs
// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/external/:path*',
        destination: 'https://external-api.com/:path*'
      }
    ];
  }
};

User not authenticated
Session expired

# 1. Check auth configuration
cat lib/auth.ts

# 2. Verify environment variables
echo $AUTH_SECRET        # Should not be empty
echo $AUTH_TRUST_HOST   # Should be true for development

# 3. Clear auth cookies
# In browser DevTools → Application → Cookies → Clear All

# 4. Check database auth tables
pnpm db:studio
# Verify user, account, session tables exist

# 5. Test auth flow
curl -c cookies.txt http://localhost:3000/api/auth/signin
curl -b cookies.txt http://localhost:3000/api/auth/session

OAuthAccountNotLinked
Callback URL mismatch

# 1. Check OAuth provider configuration
# GitHub: Settings → Developer settings → OAuth Apps
# Google: Google Cloud Console → APIs & Services → Credentials

# 2. Verify callback URLs
# Should be: http://localhost:3000/api/auth/callback/[provider]
# Not: http://localhost:3000/auth/callback/[provider]

# 3. Check environment variables
echo $GITHUB_CLIENT_ID
echo $GITHUB_CLIENT_SECRET
# Should not be empty

# 4. Test OAuth flow manually
# Visit: http://localhost:3000/api/auth/signin/github

Build failed
Module not found in production

# 1. Test production build locally
pnpm build
pnpm start

# 2. Check environment variables in Vercel dashboard
# Ensure all required env vars are set

# 3. Check build logs
vercel logs [deployment-url]

# 4. Verify dependencies
# Ensure production dependencies are not in devDependencies

# 5. Check Next.js configuration
cat next.config.js  # Should not have development-only settings

ReferenceError: process is not defined
Environment variable not accessible

# 1. Check client vs server variables
# Client variables MUST be prefixed with NEXT_PUBLIC_
NEXT_PUBLIC_API_URL="https://api.example.com"  # ✅ Client accessible
DATABASE_URL="postgresql://..."                # ❌ Server only

# 2. Verify environment files
ls -la | grep .env
# Should see: .env, .env.local, .env.example

# 3. Check variable naming
echo $DATABASE_URL      # Server-side
echo $NEXT_PUBLIC_API_URL  # Client-side

# 4. Restart development server after env changes
pnpm dev

# System requirements
node --version     # Should be 18+
pnpm --version    # Should work
git --version     # Should work

# Project health
pnpm install           # Dependencies
pnpm build:packages    # Shared packages
pnpm type-check       # TypeScript
pnpm lint:changed     # Code quality
pnpm test             # Tests

# Services
pnpm dev              # Development server
pnpm db:studio        # Database connection
curl http://localhost:3000/debug  # Debug panel

# Nuclear option - full reset
pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build:packages
pnpm dev

# Database reset (CAUTION: Deletes all data)
pnpm db:reset
pnpm db:seed

# Git reset (CAUTION: Loses uncommitted changes)
git reset --hard HEAD
git clean -fd

# System information
node --version
pnpm --version
uname -a  # macOS/Linux
systeminfo  # Windows

# Project information
git status
git log --oneline -5
pnpm list --depth=1

# Error reproduction
# Step-by-step instructions
# Full error messages
# Screenshots if applicable

## Environment
- OS: macOS 13.0
- Node: v18.17.0
- pnpm: 8.6.12
- Solo Kit: 0.7.1

## Steps to Reproduce
1. Run `pnpm dev`
2. Navigate to `/dashboard`
3. Click on user profile
4. Error appears

## Expected Behavior
User profile should load

## Actual Behavior
Error: Cannot read property 'name' of undefined

## Additional Context
- Happens only on fresh database
- Works fine after seeding data
- Console shows network error