ContextWeave

Troubleshooting Guide for ContextWeave in Bolt.new

This comprehensive troubleshooting guide covers common issues you might encounter while developing or deploying ContextWeave in Bolt.new.

Quick Diagnostics

1. Health Check Commands

# Check if app is running
curl http://localhost:3000/api/health

# Check Node.js version
node --version

# Check npm version
npm --version

# Check package installation
ls node_modules | wc -l

# Check environment variables
env | grep NEXT_PUBLIC

2. Common Status Checks

# Check development server
ps aux | grep next

# Check port usage
lsof -i :3000

# Check disk space
df -h

# Check memory usage
free -h

Development Issues

1. App Won't Start

Symptoms:

  • npm run dev fails
  • Port 3000 already in use
  • Module not found errors

Solutions:

# Kill existing processes
pkill -f next
pkill -f node

# Clear cache and reinstall
rm -rf node_modules package-lock.json .next
npm cache clean --force
npm install

# Try different port
npm run dev -- -p 3001

# Check for syntax errors
npm run lint
npm run type-check

2. Hot Reload Not Working

Symptoms:

  • Changes not reflected in browser
  • Need to manually refresh

Solutions:

# Restart development server
npm run dev

# Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

# Check file watchers
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf

# Restart Bolt.new if needed

3. TypeScript Errors

Symptoms:

  • Red squiggly lines in editor
  • Build fails with type errors

Solutions:

# Check TypeScript configuration
cat tsconfig.json

# Run type checking
npm run type-check

# Common fixes:
# 1. Add missing type imports
import { NextRequest, NextResponse } from 'next/server'

# 2. Fix component prop types
interface Props {
  children: React.ReactNode
}

# 3. Add type assertions
const data = response.json() as ApiResponse

4. Import/Export Errors

Symptoms:

  • Module not found
  • Cannot resolve module
  • Unexpected token errors

Solutions:

# Check file paths
ls -la components/
ls -la lib/

# Verify import statements
# Correct:
import { Button } from '@/components/ui/Button'
import { supabase } from '@/lib/supabase'

# Check tsconfig.json paths
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

API Issues

1. API Routes Not Working

Symptoms:

  • 404 errors on API calls
  • API routes not found
  • CORS errors

Solutions:

# Check API route files exist
ls -la app/api/

# Verify route structure
app/api/generate-context/route.ts  # Correct
app/api/generate-context.ts        # Incorrect

# Test API routes directly
curl http://localhost:3000/api/generate-context

# Check for proper exports
export async function GET(request: NextRequest) {
  return NextResponse.json({ message: 'Hello' })
}

export async function POST(request: NextRequest) {
  const body = await request.json()
  return NextResponse.json({ received: body })
}

2. External API Failures

Symptoms:

  • Libraries.io API returns errors
  • GitHub API rate limited
  • Google Search API fails

Solutions:

# Check API keys
echo $LIBS_IO_KEY
echo $GOOGLE_API_KEY
echo $GH_PAT

# Test API keys manually
curl -H "Authorization: Bearer $LIBS_IO_KEY" \
  "https://libraries.io/api/search?q=react"

# Implement fallbacks
const getFallbackData = () => {
  return [
    { name: 'react', ecosystem: 'npm', description: 'React library' },
    { name: 'express', ecosystem: 'npm', description: 'Express framework' }
  ]
}

# Add error handling
try {
  const response = await fetch(apiUrl, { headers })
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`)
  }
  return await response.json()
} catch (error) {
  console.error('API call failed:', error)
  return getFallbackData()
}

3. CORS Issues

Symptoms:

  • CORS policy errors in browser
  • Preflight request failures

Solutions:

// Add CORS headers to API routes
export async function GET(request: NextRequest) {
  const response = NextResponse.json({ data: 'example' })
  
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
  
  return response
}

export async function OPTIONS(request: NextRequest) {
  return new NextResponse(null, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

Database Issues

1. Supabase Connection Failures

Symptoms:

  • Cannot connect to Supabase
  • Authentication errors
  • Database query failures

Solutions:

# Check environment variables
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

# Test connection manually
curl -H "apikey: $NEXT_PUBLIC_SUPABASE_ANON_KEY" \
  "$NEXT_PUBLIC_SUPABASE_URL/rest/v1/"

# Verify Supabase project is active
# Check Supabase dashboard for project status

# Test in browser console
import { supabase } from '@/lib/supabase'
supabase.auth.getSession().then(console.log)

2. Authentication Issues

Symptoms:

  • GitHub OAuth not working
  • User not authenticated
  • Session not persisting

Solutions:

# Check OAuth configuration
# Verify GitHub OAuth app settings:
# - Homepage URL matches your domain
# - Callback URL: https://your-project.supabase.co/auth/v1/callback

# Check Supabase auth settings
# - Site URL matches your domain
# - Additional redirect URLs include localhost:3000

# Test auth flow step by step
1. Click sign in button
2. Check redirect to GitHub
3. Authorize application
4. Check redirect back to app
5. Verify session in browser console

3. RLS Policy Issues

Symptoms:

  • Permission denied errors
  • Cannot read/write data
  • Policies not working

Solutions:

-- Check current user
SELECT auth.uid();

-- Test policy manually
SELECT * FROM profiles WHERE user_id = auth.uid();

-- Debug RLS policies
-- Temporarily disable RLS for testing (NOT in production)
ALTER TABLE profiles DISABLE ROW LEVEL SECURITY;

-- Re-enable after testing
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- Check policy definitions
SELECT * FROM pg_policies WHERE tablename = 'profiles';

Build and Deployment Issues

1. Build Failures

Symptoms:

  • npm run build fails
  • TypeScript compilation errors
  • Missing dependencies

Solutions:

# Clean build
rm -rf .next
npm run build

# Check for TypeScript errors
npm run type-check

# Check for linting errors
npm run lint

# Fix common build issues
# 1. Remove unused imports
# 2. Fix type errors
# 3. Add missing dependencies
npm install missing-package

# Check build output
ls -la .next/

2. Deployment Failures

Symptoms:

  • Netlify build fails
  • Environment variables not loaded
  • Functions not working

Solutions:

# Check build logs in deployment platform
# Common issues:

# 1. Missing environment variables
# Add all required env vars in deployment settings

# 2. Build command incorrect
# Ensure build command is: npm run build

# 3. Node version mismatch
# Set NODE_VERSION=18 in environment variables

# 4. Function timeout
# Increase function timeout in platform settings

3. Runtime Errors in Production

Symptoms:

  • App works locally but fails in production
  • 500 internal server errors
  • API routes not working

Solutions:

# Check production logs
# Look for error messages in deployment platform

# Common production issues:
# 1. Environment variables not set
# 2. API keys invalid or expired
# 3. CORS configuration incorrect
# 4. Database connection issues

# Test production environment locally
npm run build
npm start

# Check environment variables in production
console.log(process.env.NODE_ENV)
console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)

Performance Issues

1. Slow Page Loads

Symptoms:

  • Pages take >5 seconds to load
  • Large bundle sizes
  • Slow API responses

Solutions:

# Analyze bundle size
npm run build
npm run analyze  # if configured

# Check for large dependencies
npx depcheck
npx bundle-analyzer .next/static/chunks/*.js

# Optimize images
# Use Next.js Image component
import Image from 'next/image'

# Implement lazy loading
const LazyComponent = dynamic(() => import('./Component'), {
  loading: () => <p>Loading...</p>
})

2. Memory Issues

Symptoms:

  • Out of memory errors
  • High memory usage
  • App crashes

Solutions:

# Check memory usage
free -h
ps aux --sort=-%mem | head

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run dev

# Check for memory leaks
# Use browser dev tools Memory tab
# Look for increasing memory usage over time

# Optimize code
# Remove unused dependencies
# Implement proper cleanup in useEffect
useEffect(() => {
  const interval = setInterval(() => {}, 1000)
  return () => clearInterval(interval)  // Cleanup
}, [])

Browser Issues

1. JavaScript Errors

Symptoms:

  • Console errors
  • Features not working
  • White screen of death

Solutions:

# Check browser console for errors
# Common errors:

# 1. Hydration mismatch
# Ensure server and client render the same content

# 2. Undefined variables
# Add proper null checks
const data = response?.data || []

# 3. Event handler errors
# Add error boundaries
class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    console.error('Error caught:', error, errorInfo)
  }
  
  render() {
    if (this.state.hasError) {
      return <h1>Something went wrong.</h1>
    }
    return this.props.children
  }
}

2. Styling Issues

Symptoms:

  • CSS not loading
  • Styles not applied
  • Layout broken

Solutions:

# Check Tailwind CSS configuration
cat tailwind.config.js

# Verify CSS imports
# In app/globals.css:
@tailwind base;
@tailwind components;
@tailwind utilities;

# Check for CSS conflicts
# Use browser dev tools to inspect elements
# Look for overridden styles

# Purge CSS cache
rm -rf .next
npm run dev

3. Mobile Issues

Symptoms:

  • App not responsive
  • Touch events not working
  • Viewport issues

Solutions:

<!-- Check viewport meta tag in layout.tsx -->
<meta name="viewport" content="width=device-width, initial-scale=1" />

<!-- Test responsive design -->
<!-- Use browser dev tools device emulation -->

<!-- Fix touch events -->
<button 
  onClick={handleClick}
  onTouchStart={handleTouch}  // Add for mobile
>
  Click me
</button>

Environment Issues

1. Environment Variables Not Loading

Symptoms:

  • process.env.VARIABLE is undefined
  • API keys not working
  • Configuration not applied

Solutions:

# Check .env.local file exists
ls -la .env.local

# Verify variable names
# Must start with NEXT_PUBLIC_ for client-side
NEXT_PUBLIC_SUPABASE_URL=https://...
SUPABASE_SERVICE_ROLE_KEY=...  # Server-side only

# Restart development server after env changes
npm run dev

# Check variables are loaded
console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)

2. Path Resolution Issues

Symptoms:

  • Cannot resolve '@/components'
  • Import paths not working
  • Module not found

Solutions:

// Check tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

// Check next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
  },
}

module.exports = nextConfig

Emergency Procedures

1. Complete Reset

# Nuclear option - reset everything
rm -rf node_modules package-lock.json .next
npm cache clean --force
npm install
npm run dev

2. Rollback Changes

# If recent changes broke the app
git log --oneline -10
git reset --hard HEAD~1  # Go back 1 commit
npm install
npm run dev

3. Debug Mode

# Enable debug logging
DEBUG=* npm run dev

# Enable Next.js debug mode
NODE_OPTIONS="--inspect" npm run dev

# Check detailed error messages
npm run build 2>&1 | tee build.log

Getting Help

1. Bolt.new Support

# Use AI assistant in Bolt.new
# Ask specific questions about errors
# Share error messages and stack traces

2. Community Resources

# Next.js Discord: https://discord.gg/nextjs
# Supabase Discord: https://discord.supabase.com
# Stack Overflow: Tag questions with 'nextjs', 'supabase'

3. Documentation

# Next.js docs: https://nextjs.org/docs
# Supabase docs: https://supabase.com/docs
# Tailwind docs: https://tailwindcss.com/docs

Prevention Tips

1. Regular Maintenance

# Weekly tasks:
npm audit
npm outdated
npm run lint
npm run type-check
npm run build

# Update dependencies carefully
npm update
# Test after updates

2. Error Monitoring

# Add error boundaries
# Implement logging
# Monitor performance
# Set up alerts for critical errors

3. Testing

# Write tests for critical functionality
npm run test

# Test in multiple browsers
# Test on mobile devices
# Test with slow network

This troubleshooting guide covers the most common issues encountered when developing ContextWeave in Bolt.new. Keep this handy for quick problem resolution.