# Troubleshooting

> Learn how to troubleshoot common issues with your Nuxt Starter Kit application.

## 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](https://github.com/vitejs/vite/issues/2433).

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

```bash
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**:```bash
NUXT_PRIVATE_DATABASE_URL="postgresql://user:password@host:5432/dbname"
```
2. **Verify database is running**:```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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](https://github.com/NuxtStarterKit/nuxtstarterkit/issues)
2. Contact support via email (available to customers)