Troubleshooting

JavaScript heap out of memory error during build

The FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory error occurs when the Node.js process runs out of memory during build. This is related to this Vite issue.

Solution: Increase the memory limit by setting the NODE_OPTIONS environment variable:

NODE_OPTIONS=--max-old-space-size=8192 pnpm build

For CI/CD deployments, add this environment variable in your deployment platform's settings.

Database connection issues

If you're having trouble connecting to PostgreSQL:

1. Check connection string format:

   NUXT_PRIVATE_DATABASE_URL="postgresql://user:password@host:5432/dbname"
   

2. Verify database is running:

   psql $NUXT_PRIVATE_DATABASE_URL -c "SELECT version();"
   

3. Check firewall rules: Ensure your database accepts connections from your deployment
4. SSL/TLS issues: Some providers require SSL. Try adding ?sslmode=require to your connection string

Turborepo cache issues

If builds are failing or using stale code:

# Clear Turborepo cache
pnpm exec turbo clean

# Clear node_modules and reinstall
rm -rf node_modules
pnpm install

Layer resolution issues

If layers aren't being found:

1. Ensure layers are built: Run pnpm build from root
2. Check workspace configuration: Verify pnpm-workspace.yaml includes your layers
3. Reference by name, not path: Use 'layer-auth' not '../packages/layer-auth'

Better-auth session issues

If users are being logged out unexpectedly:

1. Check BETTER_AUTH_SECRET: Must be at least 32 characters
2. Verify BETTER_AUTH_URL: Should match your actual domain
3. Check database sessions: Verify sessions table has entries

Migration issues

If migrations fail:

# Reset migrations (WARNING: destroys data)
pnpm db:drop
pnpm db:generate
pnpm db:migrate

# Or manually apply SQL
psql $NUXT_PRIVATE_DATABASE_URL < packages/layer-auth/server/db/migrations/XXXX.sql

Type errors in development

If you're seeing TypeScript errors:

# Regenerate types
pnpm postinstall

# Or manually
nuxt prepare

Deployment fails

Common deployment issues:

1. Missing environment variables: Double-check all required vars are set
2. Database migrations not run: Run pnpm db:migrate after deployment
3. Build timeout: Increase timeout in your platform settings
4. Dependency installation: Try pnpm install --frozen-lockfile

Getting Help

If you're still stuck:

1. Review the GitHub issues
2. Contact support via email (available to customers)