Troubleshooting

Common problems when running a Hype Stack project, grouped by where they show up. Most come from environment files, skipped migrations, or origin mismatches.

Setup and install

`pnpm install` fails or packages do not link

Run installs from the repository root. The repo is a single pnpm workspace. Installing inside one app breaks linking. Use pnpm 9+, not npm or yarn.

Frontend cannot reach the API

Confirm apps/frontend/.env exists and VITE_API_BASE_URL points at the backend (default http://localhost:3000). Restart the Vite dev server after changing VITE_* values; they are baked in at startup.

Docker port already in use

Something else owns the Postgres or Valkey host port. Stop it, or change the published port in docker-compose.yml and update DATABASE_URL / VALKEY_URL to match.

Database

Migrations cannot connect

Containers may still be starting. Run docker compose ps and wait for healthy, then retry pnpm --filter @hype-stack/backend prisma:migrate. Confirm DATABASE_URL in apps/backend/.env.

Tables missing after `compose` or `template`

Pack installs merge Prisma schema but do not apply SQL. Run migrations after every pack install. See Migrations.

Types wrong after a schema change

Re-run the migrate / generate script so the Prisma client regenerates. Kysely reads those types.

Auth

Almost always an origin mismatch. Check:

FRONTEND_URL on the backend
VITE_API_BASE_URL on the frontend
WorkOS redirect URIs or Better Auth BETTER_AUTH_URL + Google callback URLs

See Authentication and the starter pack setup pages.

Add your email to SUPER_ADMIN_EMAIL, or have an existing super admin create an admin record. See Admin app.

Stuck on onboarding

Private routes send users without an organization to /onboarding. Finish org creation or accept an invite. If you already have an org and still loop, check sdk.users.me and the onboarding route guard.

Billing

Webhooks never update subscription state

For local dev, run stripe listen --forward-to localhost:3000/checkout/webhook and put the printed whsec_... into STRIPE_WEBHOOK_SECRET. In production, use the live endpoint secret and confirm events reach /checkout/webhook.

Checkout works but receipts never arrive

Receipts require RESEND_API_KEY. Without it the pack skips email on purpose.

Deploy

Provider CLI not logged in

deploy checks before creating resources. Run fly auth login or railway login, or set FLY_API_TOKEN / RAILWAY_TOKEN in CI.

Custom domain still serves the wrong origin

Set url on the target in stack.json and point DNS first. Update auth provider callbacks and FRONTEND_URL / VITE_API_BASE_URL to the custom hosts. See Deploy.

Migrations failed on release

Read the provider log for the release / pre-deploy command. Fix the SQL or connection string, then redeploy. Use --skip-migrations only when you intend to migrate out of band.

Development