Common Issues

This guide covers the most common problems and their solutions.

Installation Issues

Error: "Module not found"

Symptom:

Error: Cannot find module 'framer-motion'
Module not found: Can't resolve '@ai-sdk/google'

Cause: Missing dependencies or corrupted node_modules

Solution:

# Remove node_modules and lock file
rm -rf node_modules package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
npm install

# Restart dev server
npm run dev

Error: "Node version not supported"

Symptom:

error: The engine "node" is incompatible with this module

Cause: Node.js version is too old

Solution:

# Check your version
node --version

# Install Node.js 18.17+ from nodejs.org
# Or use nvm:
nvm install 18
nvm use 18

# Reinstall and run
npm install
npm run dev

Error: "Port 3000 already in use"

Symptom:

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

Cause: Another process is using port 3000

Solution 1 - Use different port:

npm run dev -- -p 3001

Solution 2 - Kill the process (macOS/Linux):

lsof -ti:3000 | xargs kill

Solution 3 - Kill the process (Windows):

netstat -ano | findstr :3000
taskkill /PID <PID_NUMBER> /F

API & Environment Issues

Error: "API key not configured"

Symptom:

• Chat doesn't work

• Console shows API key errors

• Blank responses

Solution:

1. Create .env.local in root directory:

touch .env.local

1. Add your API key:

GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here

1. Verify the variable name is exactly as shown (common typo)

2. No quotes around the value

3. Restart the dev server:

# Stop with Ctrl+C, then:
npm run dev

1. Check file location - must be in root, not in app/ folder

Error: "API request failed"

Symptom:

Failed to fetch
Network error
429 Too Many Requests

Causes & Solutions:

1. Invalid API key:

• Go to Google AI Studio

• Verify key is active

• Generate new key if needed

• Update .env.local

2. Rate limit exceeded:

• Google AI free tier has limits

• Wait 1 minute and try again

• Consider upgrading API tier

3. Network issues:

• Check internet connection

• Disable VPN temporarily

• Check firewall settings

4. API service down:

• Check Google AI status

• Try again later

Environment variables not loading

Symptom: Variables work locally but not in production

Solution for Vercel:

1. Go to Project → Settings → Environment Variables

2. Add GOOGLE_GENERATIVE_AI_API_KEY

3. Select all environments (Production, Preview, Development)

4. Redeploy the project

Solution for local:

1. Verify file is named .env.local exactly

2. Restart dev server after changes

3. Check .gitignore includes .env.local

Build Issues

Error: "Build failed"

Symptom:

npm run build
Error: Build failed with X errors

Common causes:

1. Syntax errors:

# Check for missing brackets, quotes, etc.
npm run lint

2. Import errors:

// ❌ Wrong
import { Component } from 'wrong-path';

// ✅ Correct
import { Component } from './correct-path';

3. Type errors (if using TypeScript):

# Fix type issues or add @ts-ignore

4. Environment variables:

# Ensure all required env vars exist in build environment

General solution:

# Clean build cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules
npm install

# Try building again
npm run build

Error: "Tailwind CSS not working"

Symptom:

• No styles applied

• Plain HTML appearance

• Missing colors

Solution:

1. Verify Tailwind installation:

npm install -D tailwindcss@^4 @tailwindcss/postcss@^4

1. Check globals.css has:

@import 'tailwindcss';

1. Verify import in layout.js:

import './globals.css';

1. Clear cache and rebuild:

rm -rf .next
npm run dev

Runtime Issues

Cooldown doesn't work

Symptom: Can send multiple messages without waiting

Solution:

1. Check browser console for JavaScript errors

2. Verify localStorage is enabled:

// Test in browser console
localStorage.setItem('test', 'value');
console.log(localStorage.getItem('test')); // Should show 'value'

1. Clear localStorage:

// In browser console
localStorage.clear();

1. Refresh the page and try again

Cooldown stuck at 50 seconds

Symptom: Countdown never decreases

Solution:

1. Check browser console for errors

2. Clear localStorage:

localStorage.removeItem('lastSubmitTime');

1. Refresh the page

2. Check useEffect is working:

// Should see countdown decrease every second
console.log('Cooldown:', cooldownRemaining);

Messages not displaying

Symptom:

• Send message but nothing appears

• Blank chat area

• No error messages

Solution:

1. Check browser console for errors

2. Verify API is responding:

# Test endpoint manually
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"test"}]}'

1. Check network tab in DevTools:

• Is request being sent?

• What's the response status?

• Any errors?

1. Verify useChat hook is working:

console.log('Messages:', messages);
console.log('Status:', status);

Streaming responses are slow

Symptom: AI takes 30+ seconds to respond

Causes & Solutions:

1. Web search is slow (expected):

• Searches take 5-15 seconds

• This is normal for real-time data

• Consider reducing search requirements

2. Large max tokens:

// Reduce from 4000 to 2000
maxTokens: 2000;

3. Network latency:

• Check internet speed

• Try different network

• Disable VPN

4. Google AI API slow:

• Try at different time

• Check API status

• Consider different region

UI Issues

Matrix rain causing lag

Symptom: Animations are choppy, page is slow

Solution 1 - Disable on mobile:

const [isMobile, setIsMobile] = useState(false);

useEffect(() => {
  setIsMobile(window.innerWidth < 768);
}, []);

{
  !isMobile && <MatrixRain />;
}

Solution 2 - Reduce complexity:

// In MatrixRain.js
// Reduce number of columns
const columnCount = Math.floor(canvas.width / 10); // Increase 10 to 20

Solution 3 - Remove completely:

// Comment out in page.js
// <MatrixRain />

Styles not updating

Symptom: CSS changes don't appear

Solution:

1. Hard refresh browser:

   • Chrome/Firefox: Ctrl+Shift+R (Cmd+Shift+R on Mac)

   • Safari: Cmd+Option+R

2. Clear .next folder:

rm -rf .next
npm run dev

1. Check Tailwind classes are correct:

// ✅ Correct
className = 'bg-black text-white';

// ❌ Wrong (custom CSS needed)
className = 'custom-style';

Icons not showing

Symptom: Square boxes instead of icons

Solution:

1. Verify lucide-react is installed:

npm install lucide-react

1. Check import:

import { Eye, Send, Loader2 } from 'lucide-react';

1. Clear cache and reinstall:

rm -rf node_modules .next
npm install
npm run dev

Deployment Issues

Vercel build fails

Symptom: Deployment fails with build errors

Solution:

1. Test build locally first:

npm run build

1. Check build logs in Vercel Dashboard

2. Verify environment variables are added

3. Ensure Node version matches:

// package.json
{
  "engines": {
    "node": ">=18.17.0"
  }
}

1. Check for ESLint errors:

npm run lint

Function timeout on Vercel

Symptom:

Error: Function exceeded maximum duration of 10s

Cause: Vercel Hobby plan has 10-second limit

Solutions:

Option 1 - Upgrade to Pro ($20/month):

• 60-second limit

• Better support

• More resources

Option 2 - Reduce timeout:

// app/api/chat/route.js
export const maxDuration = 10; // Down from 50

Then adjust cooldown in app/app/page.js to match.

Option 3 - Use different host:

• Railway

• Render

• Self-hosted

Domain not working

Symptom: Custom domain doesn't load

Solution:

1. Wait 24-48 hours for DNS propagation

2. Verify DNS records:

Type: A
Name: @
Value: 76.76.21.21

Type: CNAME
Name: www
Value: cname.vercel-dns.com

1. Check DNS propagation:

• Visit whatsmydns.net

• Enter your domain

• Check if records are propagating

1. Verify in Vercel Dashboard:

• Settings → Domains

• Check for error messages

• SSL certificate status

Performance Issues

Page loads slowly

Optimization checklist:

1. Optimize images:

// Use Next.js Image component
import Image from 'next/image';
<Image src="/logo.png" width={100} height={100} />;

1. Reduce animations:

// Disable or simplify animations
transition={{ duration: 0.2 }} // Reduce from 0.5

1. Code splitting:

// Lazy load components
const MatrixRain = dynamic(() => import('./components/MatrixRain'), {
  ssr: false,
});

1. Analyze bundle:

npm run build
# Check .next/analyze for bundle size

High API costs

Symptom: Google AI bill is high

Solutions:

1. Reduce max tokens:

maxTokens: 2000; // Down from 4000

1. Implement caching:

// Cache common queries
const cache = new Map();

1. Increase cooldown:

// 60 seconds instead of 50
if (timeSinceLastSubmit < 60) { ... }

1. Monitor usage:

• Check Google AI Studio quota

• Set up billing alerts

• Track usage per day

Getting More Help

If your issue isn't listed here:

1. Check the logs:

   • Browser console

   • Terminal output

   • Vercel logs (if deployed)

2. Search GitHub Issues:

   • Existing issues

   • Someone may have solved it

3. Ask for help:

   • Open an issue

   • Join Discord

   • Include error messages and logs

4. Read related docs:

   • FAQ

   • API Reference

   • Configuration

---

Still stuck? Open an issue with detailed information and we'll help you out!