GenerateSaaSTroubleshooting
Fix common development and deployment errors fast, from missing environment variables and background jobs not firing locally to unauthenticated server fetches.
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 |
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 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.
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.
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.