Skip to content

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.md
new file mode 100644
index 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.