troubleshoot

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).