Troubleshooting

Gather minimal evidence

Record the Git commit, Node/pnpm versions, URL, command, failure stage, and redacted error. Distinguish development, preview, and production. Do not share real .env, cookies, keys, codes, signatures, or customer details.

Initialization and types

Use Node 22.12+ and pnpm 10.26.2 with the committed lockfile. Application initialization is pnpm muse:init; pnpm init is a package-manager command, not its replacement. Build before type-check when routeTree or Paraglide modules are absent. Missing local tables require checking init migrations and Wrangler state. Repeated init preserves existing passwords; MUSE_SEED_PASSWORD only affects initial account creation.

Sign-in and mail

/auth/login defaults to email codes. Password sign-in is /auth/password. Inspect /dev/mail locally after requesting a code; production requires actual delivery. Do not look for a password field on the code screen.

• Invalid/expired code: use the latest message and check resend/verification behavior.
• Redirect loop or Origin rejection: compare APP_URL with the browser, including localhost versus 127.0.0.1.
• Missing OAuth: provide both provider values and inspect public auth configuration.
• Callback failure: compare the final HTTPS origin and /api/auth/callback/google or github.
• Turnstile failure: check TURNSTILE_SITE_KEY, TURNSTILE_SECRET, and allowed domains.
• Production mail failure: inspect EMAIL, verified sender domain, MAIL_FROM, and service errors. Do not expose the development inbox.

Workbench and files

For 401, inspect the session/key. For 403, inspect role, verified email, ownership, and Origin. File keys do not authorize chat or admin operations.

Upload failures require checking nonzero bytes, 1 MiB maximum, allowed MIME, and file-count quota. For metadata without downloadable bytes, inspect R2_BUCKET and the intended object. Making the bucket public is not an ownership fix.

Admin tables filter/paginate loaded records. Check query scope and environment before treating the visible table as a database-wide result.

AI and pending work

Local studios use mock mode. Live OpenAI calls need AI_MODE=live and OPENAI_API_KEY in apps/web/.dev.vars; deployed Workers need the corresponding secret. A missing key hides media models and causes text configuration errors without a silent fallback. Video needs its separate provider key. Only local Workers AI needs WORKERS_AI_REMOTE=true and wrangler login. For media tasks, 402 means insufficient credits, 429 too many unfinished tasks and 503 the daily budget. Summaries process the first 16,000 characters of owned text/Markdown. Videos unfinished after 30 minutes fail and return credits.

For pending work, inspect JOBS, consumers, cron, outbox, and leases. Retrying must not charge again. Inspect uncertain outcomes before modifying balances. Dead-letter recovery retains administrative authorization and audit.

Payments and missing credits

Billing starts disabled. Enabling requires defaultGateway, product mappings, and all secrets. Keep test/live environments consistent; webhooks use /api/webhooks/<gateway>.

A browser return does not prove signed-event processing. Inspect orders, webhook state, and ledger entries. Duplicate events must not grant again. For uncertain refunds, inspect the provider first. Refund and cancellation are separate, and partial refunds do not automatically reverse credits proportionally.

Deployment stages

pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --json
pnpm muse:verify --target production --json

For missing inputs, inspect process > root .env > target secrets JSON precedence. For account mismatch, inspect credentials and deployment state without bypassing safeguards. Unexpected create actions require checking all five resource names before creating an empty database/bucket.

Review and handle risky SQL independently. Fix preflight diagnostics instead of skipping checks. For custom-domain smoke failures, inspect DNS/HTTPS and health environment, then verify again after propagation. Worker rollback does not reverse migrations.

Exit 2 means blocked and 3 means smoke failure. Exit 0 and smokePassed do not certify real mail, payments, or AI. See the complete deployment and testing guides.