GenerateSaaSTroubleshooting
Symptom-to-fix table for the errors you are most likely to hit - missing env vars, background jobs not firing locally, unauthenticated server fetches, and edge-incompatible modules.
Quick fixes mapped symptom to cause. Each row links the guide where the underlying pattern is documented in full.
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 | Run pnpm dev:inngest alongside your app |
Server-side fetch comes back 401/anonymous while the browser call works | A hand-rolled fetch in a Server Component drops the session cookie | Use getServerApi() so the request's cookie header forwards - see data fetching |
| App can't read an env var | Missing from .env, wrong public prefix, or a 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 on the Node runtime - see Vercel deployment |
Edits to packages/database/src/db/auth.ts keep disappearing | The file is 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 |
| Production login redirects fail | Your live origin is in neither config.origins nor TRUSTED_ORIGINS | List the origin explicitly - baseUrl is never auto-trusted. See environment variables |
Background jobs not running locally
All background work runs through the Inngest client (packages/runtime/src/inngest.ts, whose id comes from INNGEST_APP_ID), which needs a local dev server.
Start the dev server next to your running app:
pnpm dev:inngesthttp://127.0.0.1:8288 to inspect events, replay runs, and debug failures./inngest endpoint, served under the API base path derived from API_URL.See background jobs for defining and triggering jobs.
Server fetches come back unauthenticated
A Server Component's fetch does not carry the browser's session cookie by itself.
getServerApi()(lib/api/server.ts) forwards the incoming request'scookieheader and targets the absoluteNEXT_PUBLIC_API_URL. Use it for every server-side API call.- A hand-rolled
fetchwithout that header reaches the backend as an anonymous request. - Full pattern: data fetching.
geoip-lite, ioredis, and pg run only in the Node runtime - this boilerplate does not target edge or Cloudflare Workers. A runtime error that appears only after deploying usually means one of them executed in an edge context. See Vercel deployment.