# TROUBLESHOOTING

## `prisma generate` / `prisma migrate` fails with "403 Forbidden" on binaries.prisma.sh

**Symptom:**
```
Error: Failed to fetch the engine file at https://binaries.prisma.sh/... - 403 Forbidden
```

**Cause:** Prisma downloads its query-engine/schema-engine binaries from
`binaries.prisma.sh` on first use. If you're on a network with an
allowlist-based egress proxy (this project was authored inside such a
sandbox) and that domain isn't on the allowlist, the download is blocked.

**This is an environment/network issue, not a bug in this codebase.** On a
normal developer machine, CI runner, or production host with standard
internet access, `npx prisma generate` works with no special configuration.

**Fixes, in order of preference:**
1. Run `npm install && npx prisma generate` on a machine/CI runner with
   unrestricted internet access, then commit/deploy the generated
   `node_modules/.prisma` client as part of your normal build step (this is
   standard practice — Prisma Client is regenerated on every `npm install`
   via its `postinstall` hook, so most teams never think about this).
2. If you must work behind a restrictive proxy long-term, add
   `binaries.prisma.sh` to your egress allowlist.
3. As a last resort, Prisma supports `PRISMA_ENGINES_MIRROR` to point at an
   internal mirror that replicates the same path structure
   (`/all_commits/<hash>/<platform>/<file>.gz`) — only worth setting up if
   your organization already runs such a mirror for other tools.

## `DATABASE.md` migration fails with "relation already exists"

You likely ran `prisma migrate dev` against a database that already has
tables from a previous manual attempt. Either point `DATABASE_URL` at a
fresh database, or run `npx prisma migrate reset` (⚠️ destructive — wipes
all data, only use in development).

## Login fails right after registration

Check that `JWT_ACCESS_SECRET` in `.env` is set to a real value — the code
falls back to a placeholder string in development, which still works
end-to-end but should never be used outside local development.

## Activation code says "already used" but I never used it

Codes have a `processing` state held for up to 5 minutes during account
creation to prevent double-claims (see `ActivationService`). If a request
crashed mid-registration, the code self-releases back to `unused`
automatically after that window — retry after a few minutes, or check the
`activation_codes` table directly.

## Build failure: "Cannot find module '@prisma/client'"

Run `npx prisma generate` at least once after `npm install` (see the first
entry above for network requirements) — the client is generated from
`prisma/schema.prisma` into `node_modules/@prisma/client` and isn't
published as a static package.

## AdMob / Billing endpoints return 503

Both are intentionally gated behind `feature_flags` and default to
disabled — see `docs/01-ANALYSIS-ARCHITECTURE-DB-API-MIGRATION.md` §6.2 and
§6.5 for why, and flip the relevant flag in the `feature_flags` table once
the underlying business decision is made.