Local Troubleshooting

Use this page after Local Dev Setup is complete and a running local workflow needs recovery. Keep first-run installation and startup steps on the setup page.

Auth And HTTPS

If web auth session flows fail, verify the app-local .env files exist, web AUTH_BASE_URL points to apps/auth, and auth-side AUTH_UI_BASE_URL plus CORS_ORIGINS include the web origin.

If you smoke-test a built web Nitro server on a temporary local origin, add that origin to auth-side AUTH_WEB_ADDITIONAL_UI_ORIGINS and CORS_ORIGINS before starting bun run dev. That uses the same shared web-user auth policy as local web-token-replacer; do not add a preview-only auth bypass or helper script.

If an OAuth provider needs HTTPS callbacks, start the local proxy flow:

bun run dev:auth-https:up

If browser E2E fails because apps/dev-proxy/certs/auth.dev.local.pem is missing, generate local certificates once:

bun run dev:auth-https:certs

CMS Sessions

If a CMS admin session does not survive a local server restart, verify that the CMS app has a stable CMS_CUSTOMER_PAYLOAD_SECRET or CMS_LEVERAGE_PAYLOAD_SECRET.

Payload native sessions are not shared with Better Auth. Web sign-in checks and CMS admin sign-in checks are separate paths.

MongoDB And Prisma

If Prisma-backed connector flows fail against Mongo, re-check authSource=admin, replicaSet=rs0, and directConnection=true where required.

After changing API Prisma Mongo models or indexes, run the explicit schema/index sync, then audit drift:

bun run --cwd apps/api db:push-local
bun run --cwd apps/api db:audit-drift

See Prisma ORM for why this stays explicit instead of running automatically.

If local app writes suddenly fail and it is unclear whether the cause is app code or local Mongo state, run:

bun run doctor:local:mongo

MongoDB Compass is fine for browsing or intended local data edits, but its connection state is not a substitute for the app runtime path. Trust bun run doctor:local:mongo and app health checks over Compass alone.

Local Chat Data

Use this only when local chat data is stale after chat persistence, branching, queue, feedback, or Mastra memory changes.

Run the reset only from an explicit development process. For a persistent local reset setup, set both values in apps/api/.env:

NODE_ENV=development
CHAT_DATA_CLEAR_ENABLED=true

Then run:

bun run chat:data:clear

The command is development-only, requires interactive confirmation, and clears local chat threads/branches, branch response-template selections, HITL, feedback, skill-selection, and matching Mastra memory records for the selected scope.

If you need to clear one user’s records only, set USER_ID=<user-id> in apps/api/.env before running the same command.

Feedback records live in cms-customer, so keep local customer CMS reachable with matching CMS_CUSTOMER_BASE_URL and CMS_CUSTOMER_SERVICE_API_KEY before running it.

One-off shell override

Use shell overrides only for one-off local recovery when changing apps/api/.env would be noisier than the command itself.

NODE_ENV=development CHAT_DATA_CLEAR_ENABLED=true bun run chat:data:clear
USER_ID=<user-id> NODE_ENV=development CHAT_DATA_CLEAR_ENABLED=true bun run chat:data:clear

Processes And Browser Automation

If the machine is laggy or you suspect stale repo-owned Bun, Node, Turbo, or agent-browser automation processes, start with a safe report:

bun run doctor:processes

Add --clean only after reviewing the report and confirming with y:

bun run doctor:processes --clean

bun run doctor:processes --clean --include-test-runners is intentionally more aggressive. Use it only after confirming the long-running repo test processes are abandoned.

For browser automation, list and close sessions you started:

bun run agent-browser:sessions
bun run agent-browser:close:web
bun run agent-browser:close:cms-customer
bun run agent-browser:close:cms-leverage

Use agent-browser close --all only when you intentionally own every open Agent Browser session.

Authenticated Browser Sessions

Put the corresponding AGENT_BROWSER_*_EMAIL and AGENT_BROWSER_*_PASSWORD values in the root .env first. CMS login users must be verified in Payload before the helpers can sign in.

bun run agent-browser:login:web
bun run agent-browser:login:cms-customer
bun run agent-browser:login:cms-leverage

Open helpers:

bun run agent-browser:open:web
bun run agent-browser:open:cms-customer
bun run agent-browser:open:cms-leverage

The web helper loads Better Auth’s session cookie. The CMS helpers load Payload’s native auth cookies. The open helpers launch headed sessions with the repo-local reddish Chrome theme. If a session was already running without the tint, close and reopen it because Chrome loads theme extensions at browser launch.

Playwright

bun run test:local runs Playwright-owned Auth, Web, and Customer CMS servers on isolated 340x ports by default.

If you set PLAYWRIGHT_AUTH_BASE_URL=http://localhost:3001 for a local run, stop the live API first so it cannot talk to the Playwright auth server.

MCP Drift

If Codex says project-local config is disabled until the project is trusted, trust the repo from Codex’s prompt, or add the exact absolute path Codex reports to user-level ~/.codex/config.toml:

[projects."/absolute/path/to/ai"]
trust_level = "trusted"

Do not add [projects.*] or trust_level to repo-local .codex/config.toml.

If Codex warns that project-local keys such as profiles, profile, default_profile, or projects were ignored, move those settings to user-level ~/.codex/config.toml. Repo-local .codex/config.toml is generated for MCP servers plus optional repo model defaults only.

If Codex, Air, or assistant MCP servers look out of date, regenerate the repo-owned MCP config:

bun run mcp:generate

Commit the regenerated config files in the same change that changed MCP config inputs.

After trust and regeneration, verify Codex sees the repo-managed MCP servers:

codex mcp list

Page	Why you would open it
Local Dev Setup	First-run installation, startup, and health checks
Verification + Evals	Choosing the right test, build, or browser check
Bruno API Collections	Manual local API request checks
MCP Setup	MCP config ownership and generated assistant settings
Prisma ORM	MongoDB schema/index sync and Prisma workflow details

Canonical Sources

README_TESTS.md
package.json
apps/api/package.json
apps/api/scripts/clearChatData.ts
apps/api/scripts/loadApiEnvFiles.ts
apps/api/.env.example
apps/web/playwright.config.ts
apps/cms-customer/playwright.config.ts
config/mcp/servers.json
scripts/mcp/generate.ts
scripts/mcp/check.ts
scripts/processDoctor.ts