Deployment

Deployment build fails

This is most likely an issue related to the environment variables not being set correctly in the deployment environment. Please analyse the logs of the deployment provider to see what is the issue.

The kit is very defensive about incorrect environment variables, and will throw an error if any of the required environment variables are not set. In this way - the build will fail if the environment variables are not set correctly - instead of deploying a broken application.

Check our guides for the most popular hosting providers for more information on how to deploy your TurboStarter project correctly:

What should I set as a URL before my first deployment?

That's very good question! For the first deployment you can set any URL, and then, after you (or your provider) assign a domain name, you can change it to the correct one. There's nothing wrong with redeploying your project multiple times.

Sign in with OAuth provider doesn't work

This is most likely a settings issues in the provider's settings. To troubleshoot this issue, follow these steps:

1. Verify provider settings: Ensure that the OAuth provider's settings are correctly configured. Check that the client ID, client secret, and redirect URI are accurate and match the values in your application.
2. Check environment variables: Confirm that the environment variables for the OAuth provider are set correctly in your application production environment.
3. Validate callback URLs: Ensure that the callback URLs for each provider are set correctly and match the URLs in your application. This is crucial for the OAuth flow to work correctly.

Please read Better Auth documentation for more information on how to set up third-party providers.

Build runs out of memory

If the build fails with JavaScript heap out of memory:

Increase Node.js memory limit:

# In your build command
NODE_OPTIONS="--max-old-space-size=4096" pnpm build

For Vercel, add to vercel.json:

{
  "build": {
    "env": {
      "NODE_OPTIONS": "--max-old-space-size=4096"
    }
  }
}

For other providers, set the NODE_OPTIONS environment variable in their dashboard.

Database connection issues in production

If you see "Connection refused" or "ECONNREFUSED" errors:

1. Check DATABASE_URL is set correctly in your hosting provider
2. Verify IP allowlist - many database providers require you to allowlist your deployment's IP addresses
3. Check SSL requirements - production databases often require SSL:

DATABASE_URL="postgresql://...?sslmode=require"

4. Verify connection pooling - serverless environments may need connection pooling (e.g., PgBouncer, Neon's pooler)

CORS errors in production

If API requests fail with CORS errors:

1. Verify NEXT_PUBLIC_URL matches your actual domain exactly (including https://)
2. Check for trailing slashes - https://example.com and https://example.com/ are different origins
3. Verify API route is deployed - check /api/status is accessible

The API automatically configures CORS based on NEXT_PUBLIC_URL.

Preview deployments not working

If preview/staging deployments have issues:

1. OAuth callbacks won't work unless you add preview URLs to your OAuth provider's allowed redirect URIs
2. Webhooks need to point to the correct environment (use separate webhook endpoints for staging)
3. Database - ensure preview uses a separate database or the same one as staging (not production)