| name | troubleshoot |
| description | Diagnose and fix this project's known environment, toolchain, build, and runtime traps (bun/node shell errors, ESLint version/commit failures, TS path/CSS errors, IAP/auth 500s, FCM iOS errors). Use when a command fails, a commit is blocked, or the app errors in a way that matches a known symptom. |
Troubleshooting (known traps → fix)
Match the symptom, apply the fix. These are recurring, non-obvious issues in this repo.
Toolchain / shell
Normal commands are bun install, bunx <tool>, bun run <script>.
- Deps missing /
node_modules/.bin empty → run bun install in that package
(no workspace hoisting — install per package).
- LOCAL-MACHINE fallback only: if
bun/bunx/bun run crash with
command not found: __work / maximum nested function level, your shell has a
broken version-manager shim (not a repo issue). Bypass it with the absolute binary
~/.bun/bin/bun for installs and node_modules/.bin/<tool> (tsc/eslint/jest/nest)
which don't go through the shim. Add TMPDIR=/tmp if the temp dir is full (ENOSPC).
Commit / lint-staged (husky pre-commit)
- Commit fails:
eslint-plugin-react ... contextOrFilename.getFilename is not a function
→ bunx eslint pulled ESLint 10 (unsupported). .lintstagedrc.json must use
package-local eslint via cd <pkg> && node_modules/.bin/eslint ... (ESLint 9). Don't use bunx.
- Commit fails:
import/no-unresolved on @/... → eslint ran from repo root so
the resolver can't find the package tsconfig.json paths. Run with cwd = the
package (cd mobile && ...) — already how .lintstagedrc.json is set.
TypeScript
- Editor
ts(2882) on import "./styles/global.css" → covered by
declare module "*.css" in mobile/nativewind-env.d.ts; restart the TS server.
- Decimal type errors after schema change → run
bun x prisma generate; Decimal
columns are Prisma.Decimal.
Backend runtime
- 500 on an authenticated endpoint using
@CurrentUser('id') → the decorator
must honor the key (data ? user?.[data] : user); @CurrentUser('id') returns a number.
- App won't boot: env validation error → a required var is missing
(
JWT_SECRET ≥32, ENCRYPTION_KEY, DATABASE_URL, S3_*). See .env.example.
- Apple webhook rejects everything →
APPLE_ROOT_CA_CERTS not set (required to
verify the JWS chain). Android webhook 401 → set GOOGLE_PUBSUB_* (fail-closed in prod).
docker-compose app won't start → command must be bunx prisma migrate deploy && bun dist/src/main.js.
Mobile runtime (FCM)
[messaging/unregistered] ... registerDeviceForRemoteMessages → iOS must call
registerDeviceForRemoteMessages before getToken (done in messaging.ts), AND
needs the aps-environment entitlement + remote-notification background mode
(app.config.ts) + APNs key in Firebase + a real device. Rebuild: bun run prebuild && bun run ios.- Push register returns 500 → see the
@CurrentUser('id') fix above.
- Bottom tab bar wrong color in dark mode → native bar follows OS appearance;
set
tabBarStyle.backgroundColor from theme in MainTabs.
When the symptom isn't here, reproduce with the package-local binary, read the full
error, and fix at the root cause (don't suppress).
