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:

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:

  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:

  3. Ask for help:

  4. Read related docs:

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

PreviousError HandlingNextConnection Problems

Last updated