Open source personal finance application
docs(troubleshooting): add Convex CLI and Better Auth fixes
Ilya Komicheva55a6bc31129
diff --git a/docs/content/en/2.development/08.troubleshooting.md b/docs/content/en/2.development/08.troubleshooting.mdnew file mode 100644index 00000000..6f520316--- /dev/null+++ b/docs/content/en/2.development/08.troubleshooting.md@@ -0,0 +1,65 @@+---+title: Troubleshooting+description: Convex CLI gotchas and known incident fixes.+navigation:+ icon: i-lucide-life-buoy+seo:+ title: Troubleshooting+ description: Non-obvious Convex CLI behaviors and resolved Better Auth incidents that may resurface during upgrades.+---++## Convex CLI++### Targeting prod++Always pass the `--prod` flag explicitly:++```bash+npx convex run --prod ...+npx convex export --prod+```++Do **not** rely on the `CONVEX_DEPLOYMENT` environment variable. The CLI auto-loads `.env.local`, which overrides the env var, so commands intended for prod will silently hit the dev deployment.++### Directory naming++Convex rejects directory names that contain hyphens. Use underscores:++```text+convex/test_utils/ # OK+convex/test-utils/ # rejected+```++### Multi-dot filenames++Files whose names contain more than one dot (e.g. `setup.helper.ts`, `foo.bar.ts`) are automatically skipped by the Convex bundler. Useful for keeping test helpers out of the deployed function set.++### Deploy with pre-existing TS errors++If the Convex function code has pre-existing TypeScript errors that block deploy, run:++```bash+npx convex deploy --typecheck=disable+```++## Better Auth++### `login?error=please_restart_the_process` on Google sign-in++**Symptom in Convex logs:**++```text+Q(adapter:findMany) ArgumentValidationError: Object contains extra field 'mode'+Failed to parse state+```++**Cause:** Version mismatch between `better-auth` and `@convex-dev/better-auth`. The component declares a peer range and rejects newer Better Auth releases that introduce schema fields it does not know about.++**Fix:** Align the two packages so the installed Better Auth version satisfies the component's peer range. For example, `@convex-dev/better-auth@^0.12.x` requires `better-auth@>=1.6.9 <1.7.0`. After the version bump:++```bash+pnpm install+npx convex dev --once --typecheck=disable+```++The second command redeploys the auth component against the realigned dependency.