# Troubleshooting Guide

## Common Issues and Solutions

### Error: Cannot find module './XXX.js'

**Symptoms:**
```
Error: Cannot find module './350.js'
Require stack:
- /path/to/web/.next/server/webpack-runtime.js
...
```

**Cause:**
This error occurs when Next.js build cache becomes corrupted or out of sync with the source code. This commonly happens after:
- Making significant code changes
- Switching git branches
- Updating dependencies
- Interrupted builds

**Solution:**

**Option 1: Using npm scripts (Recommended)**
```bash
cd web
npm run clean-build
```

**Option 2: Using the shell script**
```bash
cd web
./clean-build.sh
```

**Option 3: Manual cleanup**
```bash
cd web
rm -rf .next
rm -rf node_modules/.cache
npm run build
```

**Option 4: Clean only (without rebuild)**
```bash
cd web
npm run clean
```

### When to Use Clean Build

Use clean build when you encounter:
- Module not found errors
- Webpack chunk errors
- Stale cache issues
- After major code refactoring
- After updating Next.js or React versions
- When switching between branches with significant differences

### Prevention Tips

1. **Always clean after major changes:**
   ```bash
   npm run clean-build
   ```

2. **Use development mode for active development:**
   ```bash
   npm run dev
   ```
   Development mode handles cache better than production builds.

3. **Clean before deploying:**
   Always run a clean build before deploying to production.

4. **After pulling changes:**
   If you pull changes that modify many files, run a clean build.

## Other Common Issues

### Port Already in Use

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

**Solution:**
```bash
# Find the process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or use a different port
PORT=3001 npm run dev
```

### TypeScript Errors After Update

**Solution:**
```bash
# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clean build
npm run clean-build
```

### React Hooks Order Error

**Error:**
```
React has detected a change in the order of Hooks called by Component
```

**Cause:**
Hooks are being called conditionally or after early returns.

**Solution:**
- Move all hooks to the top of the component
- Ensure hooks are called in the same order every render
- Never call hooks inside conditions, loops, or after returns

**Example Fix:**
```tsx
// ❌ Wrong - Hook after conditional return
function Component() {
  if (loading) return <div>Loading...</div>;
  const [state, setState] = useState(0); // Hook called conditionally
  return <div>{state}</div>;
}

// ✅ Correct - Hook before conditional return
function Component() {
  const [state, setState] = useState(0); // Hook always called
  if (loading) return <div>Loading...</div>;
  return <div>{state}</div>;
}
```

## Need More Help?

If you continue to experience issues:
1. Check the browser console for detailed error messages
2. Check the terminal/server logs
3. Try restarting the development server
4. Check if all dependencies are installed: `npm install`
5. Verify Node.js version: `node --version` (should be 18.x or higher)