Troubleshooting Handbook

Installation Issues

Issue 1: PrismaClientInitializationError on Boot

Symptoms

  • Terminal shows Can't reach database server at localhost:5432.
  • Next.js throws an error 500 on the very first render.

Fix

  1. Your Docker Postgres container is either not running, or running on a port other than 5432. Check docker ps.
  2. Ensure your .env DATABASE_URL matches the Docker port credentials exactly.

Build Failures

Issue 1: Docker Out of Memory (OOM)

Symptoms

  • Running docker build hangs at the next build step and the process is KILLED.

Root Cause

  • Next.js Webpack and Turbopack minification consumes massive chunks of RAM. Free-tier cloud instances (like 1GB DigitalOcean Droplets) will crash.

Fix

  • Build the Docker image locally or via GitHub actions, push the image to Docker Hub, and pull it down to your production server instead of building on the server itself.

Multi-Tenant Schema Issues

Issue 1: Relation Not Found parsing Prisma Schema

Symptoms

  • When accessing the API, Next.js throws: Relation "Product" does not exist in schema "public".

Root Cause

  • You used the standard global PrismaClient to fetch Products. Products only exist inside business_{slug} schemas.

Fix

  • Refactor the backend code to use the Tenant DB wrapper.
// BAD
const products = await prisma.product.findMany()

// GOOD
const tenantDb = await getTenantDb(req)
const products = await tenantDb.product.findMany()

Authentication Issues

Issue 1: NextAuth "State Mismatch" during Google Login

Symptoms

  • User clicks "Login with Google", gets redirected back to Bambu, but sees Access Denied or State Mismatch.

Fix

  • Check your NEXTAUTH_URL. If you are accessing the app at 127.0.0.1 but the URL is localhost, the cookies will fail validation. Ensure the browser URL exactly equals the Next.js environment variable.

Billing Failures

Issue 1: Test Payments succeeding but Plan not Upgrading

Symptoms

  • Using the Stripe /test cards works, but the user is still stuck on the "Free" plan.

Root Cause

  • The Stripe Webhook failed to reach your local machine.

Fix

  • Are you running stripe listen --forward-to localhost:3000/api/webhooks/stripe ? Webhooks cannot penetrate NAT routers without using the Stripe CLI forwarding tool.