Troubleshooting Guide

Solutions to common problems when using Chameleon.

Build and Installation Issues

Cannot find module './impl'

Error:

Error: Cannot find module './impl'

Solution:

# Clean reinstall
rm -rf node_modules .next
pnpm install
pnpm build

Cause: Corrupted node_modules or build cache

Type errors during build

Error:

Type error: Property 'xxx' does not exist

Solution:

# Check TypeScript version
pnpm list typescript

# Reinstall dependencies
pnpm install

# Check for missing type definitions
pnpm add -D @types/node @types/react

Database Issues

Database connection refused

Error:

Can't reach database server at host:port

Solutions:

1. Check DATABASE_URL format:

   # PostgreSQL
   DATABASE_URL="postgresql://user:password@host:5432/database"
   
   # MySQL
   DATABASE_URL="mysql://user:password@host:3306/database"
   

2. Verify database is running:

   # For local PostgreSQL
   psql $DATABASE_URL -c "SELECT 1"
   
   # For local MySQL
   mysql -h host -u user -p -e "SELECT 1"
   

3. Check firewall/network:

   • Database allows connections from your IP
   • For Vercel Postgres, no extra config needed

Table doesn't exist

Error:

relation "users" does not exist

Solution:

# Run database migration
pnpm db:push

If migration prompts:

• Choose Yes to apply changes
• Choose No to abort if unsure

Migration stuck or failed

Solution:

# Force push (careful!)
pnpm db:push --force

# Or drop and recreate (loses data!)
# DROP DATABASE and recreate, then pnpm db:push

Authentication Issues

NextAuth error: Missing secret

Error:

[auth][error] MissingSecret

Solution:

Add to .env.development:

NEXTAUTH_SECRET="your-random-32-char-secret"
AUTH_SECRET="your-random-32-char-secret"

Generate secret:

openssl rand -base64 32

OAuth callback error

Error:

OAuthCallback Error: state mismatch

Solutions:

1. Check callback URL:

   # Must match exactly in OAuth provider settings
   https://your-domain.com/api/auth/callback/google
   

2. Clear browser cookies:

   • Delete site cookies
   • Try incognito mode

3. Check OAuth credentials:

   • Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET
   • Ensure they're for the correct environment

Can't sign in

Problem: Sign in button does nothing or shows error

Solutions:

1. Check NEXTAUTH_URL:

   # Development
   NEXTAUTH_URL="http://localhost:3000"
   
   # Production
   NEXTAUTH_URL="https://your-domain.com"
   

2. Restart dev server:

   # Stop server (Ctrl+C)
   pnpm dev
   

3. Check OAuth provider status:

   • Google/GitHub may be down
   • Check service status pages

Payment Issues

Checkout failed: Invalid URL

Error:

Stripe error: Invalid URL for success_url

Solution:

Set NEXT_PUBLIC_WEB_URL:

# Development
NEXT_PUBLIC_WEB_URL="http://localhost:3000"

# Vercel
NEXT_PUBLIC_WEB_URL="https://your-domain.vercel.app"

Important: No trailing slash, no @ symbol

Stripe webhook signature verification failed

Error:

No signatures found matching the expected signature

Solutions:

1. Get correct webhook secret:

   • Stripe Dashboard > Webhooks > Your endpoint
   • Copy the signing secret (starts with whsec_)

2. Update environment variable:

   STRIPE_WEBHOOK_SECRET="whsec_xxx"
   

3. Redeploy Vercel

Customer Portal error: No configuration

Error:

No configuration provided and your test mode default configuration has not been created

Solution:

1. Go to Stripe Dashboard
2. Settings > Billing > Customer portal
3. Click Activate test link or Activate
4. Configure portal settings (allow cancellations, plan switching, etc.)
5. Save configuration

Price ID not working

Problem: Payments don't create subscriptions correctly

Solution:

1. Verify pricing configuration:

   • Use Price IDs (price_...), not Product IDs (prod_...)
   • Get Price ID by clicking into product in Stripe Dashboard

2. Check Price configuration:

   • One-time: Should be "One time"
   • Recurring: Should show interval (month/year)

AI Generation Issues

Generation stuck in "processing"

Problem: Task never completes

Solutions:

1. Check Vercel logs:

   Go to Deployments > Latest > Function Logs
   Look for errors
   

2. Verify API keys:

   • Visit /admin/ai-config
   • Check provider is enabled
   • Test with demo endpoints

3. Check provider status:

   • OpenAI status: status.openai.com
   • Kling/Seedance: Check provider websites

4. Timeout issues:

   • Videos can take 1-5 minutes
   • Upgrade Vercel plan for longer timeouts

Credits not deducted

Problem: Generated content but credits unchanged

Check:

1. Vercel logs for:

   💰 [VIDEO] Deducting credits: ...
   ✅ [VIDEO] Credits deduction result: ...
   

2. Database:

   SELECT * FROM credits_trans 
   WHERE trans_type = 'ai_generation' 
   ORDER BY created_at DESC LIMIT 5;
   

3. Generation status:

   SELECT gen_id, status, credits_cost 
   FROM generations 
   ORDER BY created_at DESC LIMIT 5;
   

Note: Credits are only deducted on successful completion, not on failure.

API key error: Missing or invalid

Error:

Seedance API key setting is missing

Solutions:

1. Set in Admin AI Config:

   • Visit /admin/ai-config
   • Add the provider
   • Enter API key
   • Enable and save

2. Or set environment variable:

   SEEDANCE_API_KEY="your-key"
   

3. Redeploy if using env vars

Result URLs not displaying

Problem: Video/image generated but not showing

Check:

1. Browser console for errors
2. URL expiration - Results expire after 24 hours
3. CORS issues - Check if CDN allows embedding

Solution:

• Download results immediately
• Contact provider for longer URL validity

Deployment Issues

Vercel build fails

Error:

Build failed with exit code 1

Solutions:

1. Check build locally:

   pnpm build
   

2. Check Vercel logs:

   • Look for specific error message
   • Common: missing env vars, type errors

3. Increase build timeout:

   • Upgrade Vercel plan
   • Or optimize build (remove unused deps)

Function timeout

Error:

Task timed out after 10.00 seconds

Solutions:

1. Upgrade to Vercel Pro:

   • Free: 10s timeout
   • Pro: 60s timeout

2. Optimize code:

   • Move long tasks to background
   • Use webhooks for completion notification

3. Use Edge Functions for faster response

Out of memory

Error:

JavaScript heap out of memory

Solutions:

1. Increase Node.js memory:

   // package.json
   {
     "scripts": {
       "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
     }
   }
   

2. Optimize imports:

   • Use dynamic imports
   • Remove unused dependencies

Environment Variable Issues

Variable has spaces

Problem: Variables not working

Wrong:

DATABASE_URL = "postgresql://..."

Correct:

DATABASE_URL="postgresql://..."

No spaces around =

Variable not found

Problem: process.env.VARIABLE_NAME is undefined

Solutions:

1. Restart dev server:

   # Stop with Ctrl+C
   pnpm dev
   

2. Check file name:

   • Use .env.development for local
   • Use .env.local for local overrides
   • Don't use .env (not loaded in development)

3. For client-side variables:

   • Must start with NEXT_PUBLIC_
   • Example: NEXT_PUBLIC_WEB_URL

Variable not working in Vercel

Solutions:

1. Check environment:

   • Is it set for Production / Preview / Development?

2. Redeploy:

   • Variables only apply to new deployments
   • Click "Redeploy" after adding variables

3. Check spelling:

   • Variable names are case-sensitive

Performance Issues

Slow page load

Solutions:

1. Enable caching:

   // In API routes
   export const revalidate = 3600; // Cache for 1 hour
   

2. Optimize images:

   • Use Next.js Image component
   • Automatic on Vercel

3. Database optimization:

   • Add indexes to frequently queried columns
   • Use .limit() on all queries
   • Consider connection pooling

High database usage

Solutions:

1. Add indexes:

   CREATE INDEX idx_users_email ON users(email);
   CREATE INDEX idx_orders_user_uuid ON orders(user_uuid);
   

2. Optimize queries:

   • Select only needed columns
   • Use joins instead of multiple queries
   • Paginate results

3. Cache frequently accessed data:

   • Use in-memory cache (like AI provider keys)
   • Set appropriate TTL

Debug Tools

Check Environment Variables

Create check-env.js:

require('dotenv').config({ path: '.env.development' });

const required = [
  'DATABASE_URL',
  'NEXTAUTH_SECRET',
  'AUTH_SECRET',
  'NEXTAUTH_URL',
];

console.log('Checking environment variables:\n');

required.forEach(key => {
  const value = process.env[key];
  console.log(`${key}: ${value ? '✅ Set' : '❌ Missing'}`);
  if (value) {
    console.log(`  Value: ${value.substring(0, 20)}...`);
  }
});

Run: node check-env.js

Test API Endpoints

Use debug/apitest.http with VS Code REST Client extension to test all endpoints.

Database Query Tool

# PostgreSQL
psql $DATABASE_URL

# MySQL  
mysql -h host -u user -p database

# List tables
\dt  # PostgreSQL
SHOW TABLES;  # MySQL

# Query users
SELECT * FROM users LIMIT 5;

Getting Help

Check Logs

1. Vercel Logs:

   • Deployments > Latest > Function Logs
   • Filter by Error/Warning

2. Browser Console:

   • F12 > Console
   • Look for JavaScript errors

3. Network Tab:

   • F12 > Network
   • Check API responses

GitHub Issues

Search or create issue: github.com/chameleon-nexus/chameleon-saas/issues

Community Support

• Discord (if available)
• GitHub Discussions

Next Steps

• Environment Variables - Complete reference
• Deployment Guide - Deployment steps
• FAQ - Frequently asked questions