GenerateSaaSTroubleshooting
Fix common development and deployment errors fast, from missing environment variables and background jobs not firing locally to SSR self-request failures.
Quick fixes for the issues you're most likely to hit, mapped symptom to cause. Each entry links to the deeper guide where the underlying pattern is documented.
Symptom to fix
| Symptom | Likely cause | Fix |
|---|---|---|
API throws Invalid runtime package environment on boot | A required env var (API_URL, REDIS_URL, BETTER_AUTH_SECRET, INNGEST_*) is missing or invalid | The error names the offending key - set it in .env, then restart. See environment variables |
| Background jobs (emails, scheduled tasks, webhooks) don't fire locally | The Inngest dev server isn't running | Start npx inngest-cli@latest dev alongside your app |
| SSR self-requests fail or hang during render | Render uses an absolute same-origin URL the server can't resolve | Use relative paths for same-origin SSR fetches - see data fetching |
| App can't read an env var | Missing from .env, wrong public prefix, or stale dev server | Add the var, prefix client values correctly, restart - see environment variables |
| Runtime error only after deploying to Vercel | A Node-only module (geoip-lite, ioredis, pg) ran in an edge context | Keep that feature out of edge - see Vercel deployment |
Edits to packages/database/src/db/auth.ts keep disappearing | The file is auto-generated by Better Auth | Add fields via additionalFields in packages/auth/src/config.ts, then run pnpm --filter @repo/database auth:generate |
Sibling package fails to resolve after pnpm --filter <app> add <pkg> | Peer hashes shifted; the workspace isn't relinked | Run a workspace-level pnpm install |
Background jobs not running locally
All background work runs through the Inngest client (packages/runtime/src/inngest.ts, whose id is set from INNGEST_APP_ID), which needs a local dev server in development.
Start the dev server next to your running app:
npx inngest-cli@latest devOpen the dashboard at http://localhost:8288 to inspect events, replay runs, and debug failures.
Confirm your app is up - Inngest discovers registered functions by reaching the /inngest endpoint, served under the API base path derived from API_URL.
See background jobs for defining and triggering jobs.
SSR self-request failures
When SSR calls your own API during render, an absolute same-origin URL can fail to resolve back to the server.
- The shared data-fetching helpers already rewrite same-origin requests to relative paths.
- If you added a custom SSR fetch, make it relative too.
- Full pattern: data fetching.
Edge-incompatible features on Vercel
This boilerplate uses Node-only modules and does not target edge or Cloudflare Workers.
geoip-lite, ioredis, and pg only run in the Node runtime. A runtime error after deploying usually means one of these executed in an edge context - keep the feature on Node. See Vercel deployment.
Frequently asked questions
Why do my edits to auth.ts keep vanishing?
packages/database/src/db/auth.ts is generated by Better Auth - manual edits are overwritten. Define new columns via additionalFields in packages/auth/src/config.ts, then run pnpm --filter @repo/database auth:generate.
Why does a package stop resolving right after I install it?
pnpm --filter <app> add <pkg> can shift peer hashes for sibling workspace packages. A single workspace-level pnpm install relinks everything.
Where do I get help if my issue isn't here? Check the guide linked from the matching row above - most issues are framework- or feature-specific and documented in depth there.