Troubleshooting

A stackr command refuses to run

"There is a pending migration for service X."

A schema change (from add entity or add service) is recorded as pending and blocks further stackr subcommands until you run and acknowledge it:

cd <service>/backend && <db:migrate command>
npx stackr migrations ack <service>

This is intentional — it stops the config and the database from drifting apart.

Port already in use

Services use deterministic ports: auth :8888 / :3333, base backends from :8080, base web from :3000. If another process holds one, stop it, or pass an explicit --port when adding a service. The test profiles use a +10000 offset so they never collide with a dev stack.

Stale Docker volumes after re-generating

If a freshly generated or renamed project fails to connect to its database, an old volume is carrying the wrong credentials. Let setup reset them:

npm run setup     # answer "yes" to the volume reset prompt
# or manually:
docker compose down -v && npm run docker:dev

Cross-service auth fails (401 from a base service)

A base service authenticates by forwarding the cookie to the auth service. If protected routes 401:

1. AUTH_SERVICE_URL on the base service must point at the running auth service.
2. The cookie must reach the base service — check CORS and that the client sends credentials.
3. The auth service must be up — a base service can't verify sessions if auth is down (you'll get an external-service error).

# from the base service container, the auth check is essentially:
curl -i http://auth:8888/api/auth/get-session -H "cookie: <session cookie>"

Migrations don't apply

Make sure you're running the migrate command inside the right service's backend/ directory — each service has its own database and its own migration history. The script is db:migrate (Drizzle Kit or Prisma depending on your locked ORM).

OAuth callback fails

Usually a redirect-URI mismatch or CORS. Check that the redirect URI exactly matches the provider config, that the auth service's CORS allows your web origin, and that third-party cookies aren't blocked in dev. Apple Sign-In requires HTTPS and won't work on http://localhost — use a tunnel (e.g. ngrok http 8888) or test it on a staging host.

Mobile: Metro bundler is stuck

npx expo start -c

Build fails with module errors (web)

rm -rf <service>/web/.next <service>/web/node_modules
npm install