Skip to Content
InfrastructureDeployment & OperationsTroubleshooting

Troubleshooting Guide

Common issues and solutions for the Earna AI monorepo infrastructure.

Build Issues

PNPM Installation Failures

Symptom

ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies

Solution

# Clear cache and reinstall
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install
 
# Or allow peer deps
echo "auto-install-peers=true" >> .npmrc
pnpm install

Native Module Compilation Errors

Symptom

error: Error: Cannot find module '@napi-rs/simple-git'
error: lightningcss failed to compile

Solution

# Rebuild native modules
pnpm rebuild
 
# Or reinstall with specific platform
pnpm install --force
 
# For M1 Macs
arch -x86_64 pnpm install

Turborepo Cache Issues

Symptom

Error: Cache signature verification failed

Solution

# Clear Turborepo cache
rm -rf .turbo
 
# Force rebuild without cache
pnpm turbo build --force
 
# Reset cache completely
pnpm turbo daemon clean

Vercel Deployment Issues

Monorepo Build Failures

Symptom

Error: Cannot find package 'xyz' imported from /vercel/path

Solution

  1. Ensure VERCEL_DEEP_CLONE=true is set in environment variables
  2. Check PNPM_VERSION=9.14.4 is set
  3. Verify root directory is set correctly in Vercel settings

Preview Deployments Show 404

Symptom

Preview branches return 404, but production works

Solution

// vercel.json
{
  "buildCommand": "pnpm turbo build --filter=project-name",
  "installCommand": "pnpm install",
  "outputDirectory": ".next",
  "rootDirectory": "./"  // Must be root, not subdirectory
}

Environment Variables Not Available

Symptom

undefined reading process.env.VARIABLE_NAME

Solution

  1. For client-side: Use NEXT_PUBLIC_ prefix
  2. Check variable scope in Vercel (Production/Preview/Development)
  3. Rebuild after adding variables: vercel --force

Runtime Errors

Database Connection Failed

Symptom

PrismaClientInitializationError: Can't reach database server

Solution

# Check DATABASE_URL format
postgresql://user:pass@host:5432/db?sslmode=require
 
# For local development
DATABASE_URL="postgresql://localhost:5432/mydb"
 
# Test connection
pnpm --filter credit-engine db:push

API Rate Limits

Symptom

429 Too Many Requests from OpenAI/Anthropic

Solution

// Implement rate limiting
import { Ratelimit } from "@upstash/ratelimit"
 
const ratelimit = new Ratelimit({
  redis: redis,
  limiter: Ratelimit.slidingWindow(10, "10 s"),
})
 
// In API route
const { success } = await ratelimit.limit(identifier)
if (!success) {
  return new Response("Too Many Requests", { status: 429 })
}

Memory/Timeout Errors

Symptom

Error: Function execution timed out
FATAL ERROR: Reached heap limit

Solution

// vercel.json
{
  "functions": {
    "app/api/heavy-route.ts": {
      "maxDuration": 60,  // Increase timeout
      "memory": 3008      // Increase memory
    }
  }
}

Development Issues

Port Already in Use

Symptom

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

Solution

# Find and kill process
lsof -i :3000
kill -9 [PID]
 
# Or use different port
PORT=3001 pnpm dev
 
# For specific project
pnpm --filter console dev -- -p 3001

Hot Reload Not Working

Symptom

Changes not reflected in browser

Solution

# Clear Next.js cache
rm -rf .next
 
# Restart with cache disabled
pnpm turbo dev --force
 
# Check file watching limit (Linux/WSL)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

TypeScript Errors

Symptom

Type error: Cannot find module or type definitions

Solution

# Regenerate types
pnpm turbo typecheck --force
 
# Clear TypeScript cache
rm -rf tsconfig.tsbuildinfo
 
# Reinstall types
pnpm add -D @types/node @types/react

Git & GitHub Issues

Pre-commit Hook Failures

Symptom

Pre-commit checks failed

Solution

# Fix linting issues
pnpm turbo lint -- --fix
 
# Fix formatting
pnpm prettier --write .
 
# Skip hooks temporarily (not recommended)
git commit --no-verify

Large File Errors

Symptom

error: File is 106.24 MB; this exceeds GitHub's file size limit

Solution

# Add to .gitignore
echo "large-file.zip" >> .gitignore
 
# Remove from history
git rm --cached large-file.zip
git commit -m "Remove large file"
 
# Use Git LFS for large files
git lfs track "*.psd"
git add .gitattributes

Console-Specific Issues

Supabase Connection Errors

Symptom

Invalid API key or URL

Solution

# Verify credentials
NEXT_PUBLIC_SUPABASE_URL=https://[project].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=[correct-anon-key]
 
# Test connection
curl https://[project].supabase.co/rest/v1/

AI Provider Errors

Symptom

Error: Invalid API key for OpenAI/Anthropic

Solution

  1. Verify API key format:
    • OpenAI: sk-... (48+ characters)
    • Anthropic: sk-ant-...
  2. Check usage limits and billing
  3. Test with curl:
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Credit Engine Issues

Prisma Migration Errors

Symptom

Error: P3009 migrate found failed migrations

Solution

# Reset database (development only!)
pnpm --filter credit-engine db:reset
 
# Fix migration history
pnpm --filter credit-engine db:migrate resolve --applied [migration]
 
# Create new migration
pnpm --filter credit-engine db:migrate dev --name fix_issue

NextAuth Errors

Symptom

[next-auth][error][CLIENT_FETCH_ERROR]

Solution

# Generate new secret
openssl rand -base64 32
 
# Set in .env.local
NEXTAUTH_SECRET=[generated-secret]
NEXTAUTH_URL=http://localhost:3004  # Must match actual URL

Performance Issues

Slow Build Times

Solution

# Use Turborepo caching
pnpm turbo build
 
# Parallel builds
pnpm turbo build --concurrency=4
 
# Analyze bundle
ANALYZE=true pnpm build

Large Bundle Size

Solution

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['lodash', 'd3', '@mui/material']
  },
 
  // Tree shake unused code
  webpack: (config) => {
    config.optimization.sideEffects = false
    return config
  }
}

Docker Issues

Container Build Failures

Solution

# Use correct Node version
FROM node:20-alpine
 
# Install PNPM
RUN corepack enable
RUN corepack prepare pnpm@9.14.4 --activate
 
# Copy lock file
COPY pnpm-lock.yaml ./

Container Can’t Find Modules

Solution

# Copy all workspace files
COPY . .
 
# Install with frozen lockfile
RUN pnpm install --frozen-lockfile
 
# Build specific project
RUN pnpm turbo build --filter=console

Emergency Procedures

Production Down

  1. Check Vercel Status: https://www.vercel-status.com/ 
  2. Check Recent Deployments: vercel ls --prod
  3. Rollback if Needed: vercel rollback
  4. Check Logs: vercel logs --prod --since 1h

Database Corrupted

# 1. Stop all connections
# 2. Backup current state
pg_dump $DATABASE_URL > emergency-backup.sql
 
# 3. Restore from last good backup
psql $DATABASE_URL < last-good-backup.sql
 
# 4. Verify data integrity
pnpm --filter credit-engine db:studio

API Keys Compromised

  1. Immediately rotate all keys
  2. Update in Vercel: vercel env rm OLD_KEY && vercel env add NEW_KEY
  3. Redeploy all services: vercel --prod --force
  4. Audit logs for unauthorized usage

Getting Help

Resources

Debug Commands

# System info
npx envinfo --system --binaries --browsers
 
# Dependency tree
pnpm why [package-name]
 
# Turbo graph
pnpm turbo run build --graph
 
# Vercel diagnostics
vercel inspect [deployment-url]

Logs Location

# Turborepo logs
.turbo/turbo-build.log
 
# Next.js build logs
.next/trace
 
# Vercel logs
vercel logs --since 1h > debug.log
 
# PNPM debug
pnpm install --reporter=append-only 2> pnpm-debug.log
Last updated on
Secrets Management