Guide

This page will be updated as common issues are reported by users.

If you encounter a problem, please check our GitHub Issues or open a new discussion. We will add solutions for frequently reported problems here to help the community.

Note: If you see the same error as others, let us know! The more reports we get, the faster we can improve this guide.

Command Not Found

If you get a "command not found" error:

# For pnpm users, try:
npm install -g pnpm
pnpm dlx build-elevate@latest init

# For npm users:
npx build-elevate@latest init

# For bun users:
bunx build-elevate@latest init

Installation Fails

If the installation fails:

1. Check your Node.js version

   node --version  # Must be v20 or higher

2. Clear package manager cache

   pnpm store prune

3. Try with verbose logging

   pnpm dlx build-elevate@latest init --verbose

Port Already in Use

If you see an error like "Port 3000 is already in use", you have two options:

Option 1: Change the port (Recommended)

See Custom Ports in the Getting Started guide for how to run applications on different ports. This is the simplest solution.

Option 2: Kill the process using the port

# Find what's using the port
lsof -i :3000

# Kill the process
kill -9 <PID>

Database Connection Errors

If you encounter database connection issues:

# 1. Verify DATABASE_URL is set correctly
echo $DATABASE_URL

# 2. Check PostgreSQL is running
# For local PostgreSQL:
psql postgres://user:password@localhost:5432/dbname

# 3. Test Prisma connection
pnpm db:migrate

# 4. View databases and tables in Prisma Studio
pnpm db:studio

Authentication Not Working

If you can't sign in:

1. Verify BETTER_AUTH_SECRET is identical in both apps/api/.env.local and apps/web/.env.local. See Environment Variables Guide for generation and setup instructions.
2. Check ALLOWED_ORIGINS in apps/api/.env.local matches your web app URL
3. Clear cookies and try again

For app-specific authentication issues:

• Web app: See Web Application - Troubleshooting
• API: See API Application - Troubleshooting