Troubleshoot Grout

Start with the failing subsystem, confirm its required configuration, and run the smallest check that reproduces the problem.

Fix database and migration failures

Confirm DATABASE_URL points to the intended PostgreSQL database. Then inspect the schema and migration state:

npx prisma validate
npx prisma migrate status
npx prisma generate

Use npx prisma migrate deploy for committed migrations. Do not use the demo seed to repair production data because it deletes existing application records.

Refresh generated types

Regenerate Prisma and Next.js route types after schema or route changes:

npx prisma generate
npx next typegen
npm run typecheck

Remove only generated cache output when stale .next types reference a deleted route. Do not delete source files or reset unrelated work.

Diagnose email and text-message delivery

Open /admin/comms and inspect the recorded error. Messages remain in the outbox when delivery credentials are absent.

For email, configure every required Simple Mail Transfer Protocol (SMTP) variable. For text messages, configure TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_FROM together.

Diagnose Stripe behavior

Without STRIPE_SECRET_KEY, local development uses the mock payment gateway. Set a Stripe test key when you need to verify hosted card setup or Stripe provider responses.

If cards are refused with a Stripe key configured, the company has not connected its own Stripe account, or Stripe has not made it live. Open Settings → Payments: it names the connected account, the card-payments capability Stripe last reported, and when that was last read. Check with Stripe re-reads it immediately.

Never use live customer credentials or card data in an automated test.

Fix documentation build failures

Regenerate the Fumadocs source and run a production build:

npm run postinstall
npm run build

Check content/docs/meta.json when a new page builds but does not appear in navigation.

Fix Playwright browser failures

Install the Chromium version required by the repository:

npx playwright install chromium

Playwright starts the production server on port 3100. Stop another process using that port, or confirm the reused server points to the intended test database.

Run one failing file before running the complete suite:

npx playwright test tests/e2e/platform.spec.ts