Troubleshooting

Missing Environment Variables

Symptoms: App crashes on startup, database connection errors, auth failures, or blank pages.

1. Verify all required variables are set (see Deployment for the full list).
2. Check variable names for typos — they are case-sensitive.
3. Ensure NEXT_PUBLIC_* variables are set in the deployment platform (Vercel, Docker, K8s). These are embedded at build time.
4. Restart the application after adding or changing variables.

Database Connection Errors

Symptoms: ECONNREFUSED, ENOTFOUND, authentication errors, or "database not found".

1. Verify TURSO_DATABASE_URL is correct (libsql://your-db-name-your-org.turso.io).
2. Check that TURSO_AUTH_TOKEN is valid and has not expired.
3. Confirm the database exists: turso db list.
4. Test connectivity directly: turso db shell your-db-name.
5. Check network and firewall rules if the app runs behind a NAT or VPN.
6. For local file databases (file:local.db): ensure the directory has write permissions.

Webhook Signature Validation Failures

Symptoms: Stripe or LemonSqueezy webhooks return 401 or 403.

1. Verify that STRIPE_WEBHOOK_SECRET (or LEMONSQUEEZY_WEBHOOK_SECRET) matches the signing secret shown in the provider dashboard — not the API key.
2. Confirm the webhook URL is correct:
   • Stripe: https://app.example.com/api/webhooks/stripe
   • LemonSqueezy: https://app.example.com/api/webhooks/lemonsqueezy
3. Check the provider dashboard for recent delivery attempts and response codes.
4. Make sure the webhook endpoint is publicly accessible and not behind authentication.
5. Use the provider's webhook testing tool to send a test event.

OAuth Redirect URL Mismatch

Symptoms: OAuth login fails with "redirect_uri_mismatch" or similar error.

1. Verify BETTER_AUTH_URL (or KINDE_SITE_URL) matches your production domain exactly, including the protocol.
2. Add the correct redirect URLs in each OAuth provider's dashboard:
   • Google: https://app.example.com/api/auth/callback/google
   • GitHub: https://app.example.com/api/auth/callback/github
3. Ensure URLs use https:// in production (not http://).
4. Wait a few minutes for OAuth provider changes to propagate.

File Upload Failures

Symptoms: Uploads fail with 500 errors, or uploaded files are not accessible.

1. Verify STORAGE_PROVIDER is set correctly (s3 or r2 for production).
2. Check S3/R2 credentials, bucket name, region, and endpoint.
3. Ensure the bucket has the correct CORS policy:

   [
     {
       "AllowedOrigins": ["https://app.example.com"],
       "AllowedMethods": ["GET", "PUT", "POST"],
       "AllowedHeaders": ["*"]
     }
   ]
   

4. Verify bucket permissions allow read and write access.
5. Set S3_PUBLIC_URL if files need to be publicly accessible.
6. For local storage: ensure the upload directory exists and is writable by the application process.

Background Jobs Not Processing

Symptoms: Jobs are queued but never execute. Emails not sent. Scheduled tasks not running.

1. Verify JOB_PROVIDER=bullmq — the memory provider is for development only and does not persist across restarts.
2. Check that REDIS_URL is correct and Redis is reachable.
3. Test the Redis connection: redis-cli -u $REDIS_URL ping (should return PONG).
4. Ensure worker processes are running (if using separate workers in Kubernetes).
5. Inspect the queue: redis-cli -u $REDIS_URL LLEN bull:codapult:wait.
6. Check application logs for job processing errors.

Rate Limiting Issues

Symptoms: Legitimate requests are blocked with 429, or rate limiting is not applied at all.

1. For multi-instance deployments, use a Redis-backed rate limiter so limits are shared across instances.
2. Verify REDIS_URL is set (if using Redis-backed limiter).
3. Check the rate limit configuration in the relevant API route or src/lib/rate-limit.ts.
4. Inspect response headers: X-RateLimit-Remaining and Retry-After.
5. Adjust limits based on your traffic patterns.

Health Check Failures

Symptoms: Load balancer marks instances as unhealthy. Containers restart repeatedly.

1. Verify the /api/health endpoint responds with 200:

   curl -s http://localhost:3000/api/health
   

2. Ensure the health check path in your load balancer or orchestration platform matches /api/health.
3. Confirm the health check does not require authentication.
4. Verify the container is listening on port 3000.
5. Check application logs for startup errors.

Build Failures

Symptoms: Deployment fails during the build step. CI/CD pipeline errors.

1. Confirm the Node.js version matches (22.x recommended).
2. Ensure pnpm-lock.yaml is committed to the repository.
3. Verify all dependencies are installable: pnpm install --frozen-lockfile.
4. Review build logs for specific TypeScript or Next.js errors.
5. Test the build locally: pnpm run build.
6. If the build runs out of memory, increase the Node.js heap size:

   NODE_OPTIONS="--max-old-space-size=4096" pnpm run build
   

CORS Errors

Symptoms: Browser console shows "Access to fetch has been blocked by CORS policy".

1. Verify NEXT_PUBLIC_APP_URL matches the domain making requests.
2. Check that API routes allow the correct origin.
3. Review CORS configuration in next.config.ts or Next.js middleware.
4. Ensure preflight (OPTIONS) requests are handled correctly.

SSL Certificate Issues

Symptoms: Browser shows SSL warnings, "certificate not found", or "ERR_CERT_AUTHORITY_INVALID".

1. Verify DNS records point to the correct IP or load balancer.
2. Wait for DNS propagation (can take up to 48 hours).
3. Check certificate status in your provider dashboard (Vercel, ACM, Let's Encrypt).
4. Ensure the certificate covers all required domains (including www. if used).
5. Confirm the certificate has not expired.

Getting Help

If the issue is not covered above:

1. Check application logs (Vercel dashboard, CloudWatch, kubectl logs).
2. Review error details in Sentry (if configured).
3. Reproduce the issue locally with production environment variables.
4. Consult the Next.js docs or Turso docs.
5. Open an issue in the Codapult repository.