Troubleshooting

Start with the setup doctor:

bun check-env

Then run the smallest command that reproduces the problem.

Dependency Or Workspace Issues

Install from the repository root:

bun install

Check workspace consistency:

bun run lint:repo

If generated build state is stale, clean workspace outputs:

bun clean:workspaces

Read the root clean script before using it. It removes ignored files through git clean.

Environment Errors

Run:

bun check-env

Common causes:

• Missing NEXT_PUBLIC_CONVEX_URL in apps/app/.env.
• Missing NEXT_PUBLIC_CONVEX_SITE_URL in apps/app/.env.
• Missing CONVEX_SITE_URL, SITE_URL, or BETTER_AUTH_SECRET in packages/backend/.env.
• Backend variables set locally but not in the Convex dashboard.
• BILLING_PROVIDER set without the selected provider's required variables.

See Environment Variables.

Convex Issues

Start Convex directly:

bun dev:convex

If the backend starts locally but deployed functions fail, check that Convex environment variables are set in the Convex dashboard. Convex does not read packages/backend/.env at runtime after deployment.

Do not manually edit generated files in:

packages/backend/convex/_generated

Regenerate them with the Convex CLI when needed.

Auth Issues

Check these first:

• NEXT_PUBLIC_APP_URL in apps/app/.env.
• SITE_URL in packages/backend/.env and Convex env.
• BETTER_AUTH_SECRET in packages/backend/.env and Convex env.
• OAuth callback URLs in Google or Microsoft provider settings.
• AUTH_TRUSTED_ORIGINS for alternate local or preview origins.

Google callback:

http://localhost:3000/api/auth/callback/google

Microsoft callback:

http://localhost:3000/api/auth/callback/microsoft

Email Issues

For magic links and transactional email:

• Set RESEND_API_KEY in packages/backend/.env.
• Set RESEND_API_KEY in Convex env.
• Use verified sender domains in production.
• When using Resend's shared test sender, send only to the permitted test recipient for your account.

Preview email templates locally:

bun dev:email

Billing Issues

If billing is not part of your current setup, leave BILLING_PROVIDER unset.

If billing is enabled:

• Confirm BILLING_PROVIDER matches the provider: polar, stripe, or lemon_squeezy.
• Confirm all provider IDs map to the catalog in packages/backend/convex/billing/catalog.ts.
• Confirm provider webhook secrets are set in Convex env.
• Confirm webhooks point to the Convex site URL, not a Next.js route.

Checkout creation should not grant access by itself. Verified provider webhooks grant and revoke access.

Next.js App Issues

Run focused builds:

bun --cwd apps/app build
bun --cwd apps/marketing build

Run focused typechecks:

bun --cwd apps/app typecheck
bun --cwd apps/marketing typecheck

The product app runs on port 3000; the marketing site runs on port 3002.

Verification Commands

Use these when a fix is ready:

bun run lint
bun run typecheck
bun run test

For production confidence:

bun run build