Troubleshooting

Start with the error message and the health endpoint. Most issues are configuration or a missing service.

Setup and environment

"Missing required environment variables"

The app validates its environment at startup. The error names the missing variable. Compare .env with .env.example and check conditional requirements:

• Stripe keys are required only when STRIPE_ENABLED="true".
• Polar keys are required only when POLAR_ENABLED="true".
• S3 keys are required only when STORAGE_PROVIDER="s3".
• WhatsApp keys are required only when WHATSAPP_ENABLED="true".

"Invalid environment variables"

A value has the wrong type. Common causes: DATABASE_URL is not a valid URL, SMTP_PORT is not numeric, or a boolean is not the string "true" / "false".

Auth redirects to the wrong host

Check NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_FRONTEND_URL, and the storefront domain configuration. NEXT_PUBLIC_* values are baked at build time.

Database

Connection refused

pnpm db:dev:up

The development database listens on localhost:5432; the test database on localhost:5433. Check Docker is running and the ports are free.

Migrations out of date

pnpm db:migrate

For local-only schema experiments, pnpm db:push is available, but never run it against production. Production migrations use pnpm db:prod:migrate.

Seed fails

pnpm -F admin db:seed requires Bun and a reachable database with migrations applied. Run it from the repository root.

Storefront

No products appear

• The product must be Active and Public.
• The storefront must use the right ORGANIZATION_SLUG.
• The API key must belong to that organization.
• NEXT_PUBLIC_API_URL must point at the admin app.

API 401 or 403

• ApiKey header missing or invalid.
• The key belongs to a different organization than the slug in the path.
• The key was revoked.
• The plan does not include API access.

Images do not load

• S3_PUBLIC_URL_BASE or the Cloudinary URL must be publicly reachable.
• The storefront CSP and next/image configuration must allow the media host.
• The media row may point at the previous storage provider after a switch.

Background jobs

Emails or PDFs never happen

• Is the Inngest dev server running? pnpm dev:admin starts it.
• Are INNGEST_EVENT_KEY / INNGEST_SIGNING_KEY set in production?
• Did the function run? Check the Inngest dashboard for the failed step.
• Are SMTP or storage credentials valid?

Inngest port conflict on Windows

8288 can be reserved by Hyper-V/WSL. The repo uses 8310; keep INNGEST_DEV in sync if you override it.

Storage

Upload fails

• Check STORAGE_PROVIDER and its credentials.
• For S3, check the endpoint, region, bucket, path style, and public URL base.
• The max upload is 100 MB; content types are validated.
• Only run one local storage service (SeaweedFS or RustFS) at a time.

"Storage: error" in health

The database is reachable but storage is not. Check credentials and the storage service, then call the health endpoint again.

PDFs

• Check the Puppeteer runtime.
• Set PUPPETEER_EXECUTABLE_PATH if Chrome is not found.
• Set PUPPETEER_NO_SANDBOX="true" only in environments where sandboxing is unavailable.
• Check storage write permissions.

Docs

API pages are stale

pnpm docs:sync-api

The admin app must be running at OPENAPI_SPEC_URL (default http://localhost:3000/api/openapi.json).

Docs build fails

• Run pnpm -F docs check-types.
• Check MDX syntax and frontmatter.
• Confirm apps/docs/openapi.json exists.
• Check NEXT_PUBLIC_DOCS_URL is a valid URL.

Feature flags

• Check FEATURE_FLAGS_DISABLED first.
• Use pnpm flags -- list --org <slug> to see the resolved source.
• A rollout percentage below 100 may exclude your test organization.

Still stuck?

• Check Observability for logs and audit tables.
• Reproduce with LOG_LEVEL="debug".
• Open an issue with the command, error, environment, and reproduction steps.