Common Issues & Solutions

ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies

# Force install with legacy peer deps
pnpm install --legacy-peer-deps

# Or clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install

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

# Check current version
node --version

# Install correct version with nvm
nvm install 20
nvm use 20

# Or update package.json engines

Error: P1001: Can't reach database server at localhost:5432

# macOS
brew services list | grep postgresql

# Linux
systemctl status postgresql

# Docker
docker ps | grep postgres

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Check format
# Should be: postgresql://user:pass@host:port/db

# Allow PostgreSQL port
sudo ufw allow 5432

Error: P3005: The database schema for `postgres` is not empty

# Reset database (CAUTION: Deletes all data)
pnpm prisma migrate reset

# Or manually
pnpm prisma db push --force-reset

Error: @prisma/client did not initialize yet

# Generate Prisma Client
pnpm prisma generate

# Ensure postinstall script runs
pnpm install

Error: Invalid API key provided

# Check environment variable
echo $OPENROUTER_API_KEY

# Should start with sk-or-v1-

# Ensure no quotes or spaces
OPENROUTER_API_KEY=sk-or-v1-xxxxx

Error: Rate limit exceeded. Please try again later.

async function retryWithBackoff(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (i === retries - 1) throw error
      await new Promise(r => setTimeout(r, 2 ** i * 1000))
    }
  }
}

// Fallback to cheaper model
const model = rateLimited ? 'openai/gpt-3.5-turbo' : 'anthropic/claude-3.5-sonnet'

// Ensure using streaming endpoint
fetch('/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message })
})

// API route should return:
return new Response(stream, {
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  }
})

// Ensure user is logged in
const session = await auth()
if (!session) {
  // Guest mode - use localStorage
}

-- Check messages are saved
SELECT * FROM "Message" WHERE "chatId" = 'xxx';

// Force refetch
queryClient.invalidateQueries(['chat', chatId])

// Browser console
console.log(eventSource.readyState)
// Should be 1 (OPEN)

// Check API response includes DSL
const response = await fetch('/api/chat')
const data = await response.json()
console.log(data.dsl) // Should have DSL data

// Ensure DSL events are stored
const events = await db.query.dslEvent.findMany({
  where: eq(dslEvent.chatId, chatId)
})

❌ "I need a system"
✅ "I need a task management system with projects, tasks, and users"

❌ "Users and tasks are related"
✅ "Each user can have many tasks, tasks belong to one user"

❌ "Tasks have some fields"
✅ "Tasks have title (required), description, status (todo/done), and due date"

console.log('DSL Readiness:', dsl.readiness)
// Should be >= 75

// Should be 'confirming' or 'building'
console.log('Current phase:', dsl.phase)

// components/code-generation-panel.tsx
const canGenerate = readiness >= 75 && entityCount > 0

# Ensure all required packages installed
pnpm install

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true
  }
}

// Use @ alias consistently
import { prisma } from '@/lib/prisma'
// Not: import { prisma } from '../../lib/prisma'

// Use select to limit fields
const posts = await prisma.post.findMany({
  select: {
    id: true,
    title: true,
    // Don't fetch content if not needed
  }
})

// Cache frequently accessed data
const cached = await redis.get(key)
if (cached) return JSON.parse(cached)

// Limit results
const posts = await prisma.post.findMany({
  take: 20,
  skip: page * 20
})

// Use streaming for large data
const stream = new ReadableStream({
  async start(controller) {
    for (const chunk of data) {
      controller.enqueue(chunk)
    }
    controller.close()
  }
})

# Analyze bundle
ANALYZE=true pnpm build

# Remove unused dependencies
pnpm prune --production

# Generate new secret
openssl rand -base64 32

# Update .env.local
AUTH_SECRET=new_secret_here

// Browser console
document.cookie.split(";").forEach(c => {
  document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/")
})

-- Verify user exists
SELECT * FROM "User" WHERE email = 'user@example.com';

// auth.config.ts
export const authConfig = {
  session: {
    strategy: 'jwt',
    maxAge: 30 * 24 * 60 * 60, // 30 days
  }
}

// Refresh session before expiry
if (session.expires - Date.now() < 3600000) {
  await refreshSession()
}

vercel logs [deployment-url]

# Simulate production build
pnpm build
pnpm start

vercel --force

vercel env pull .env.local

// Common mistake: NEXT_PUBLIC_ prefix
// Client-side needs: NEXT_PUBLIC_APP_URL
// Server-side needs: APP_URL

// Polyfill for Safari
if (!window.TextEncoder) {
  window.TextEncoder = TextEncoder
}

// Fallback for older browsers
if (!window.EventSource) {
  // Use polling instead
}

// middleware.ts
export function middleware(request: NextRequest) {
  const response = NextResponse.next()
  
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
  
  return response
}

// Ensure OPTIONS handled
export async function OPTIONS() {
  return new Response(null, { status: 200 })
}

# Enable debug logging
DEBUG=* pnpm dev

# Specific module
DEBUG=prisma:query pnpm dev