Troubleshooting
Searchable reference for common issues. Ctrl+F your error message.
Quick triage: npm run type-check. If it passes, the issue is environmental (env vars, service connectivity), not code.
| Issue | Fix |
|---|
| Port in use | Run npx kill-port 3000, then npm run dev |
| TypeScript errors | npm run type-check |
| DB out of sync | npm run db:push |
| Build fails | Check .env.local, npm run build locally |
| Auth broken | Verify Supabase env vars |
| Setup wizard fails | Re-run with --dry-run, then resume or reset the project checkpoint |
| Payments failing | Check webhook secret env var |
| AI silent | GEMINI_API_KEY missing or invalid |
| Dark mode broken | Semantic tokens (bg-background), not bg-white |
| Motion too large | m from motion/react, not framer-motion |
| Translation missing | npx tsx scripts/find-missing-locale-keys.ts |
The setup wizard checkpoints each project under ~/.vibe44/setup-wizard/{projectHash}.json. It never persists apiKeys.
| Problem | Fix |
|---|
| Interrupted prompt flow | npm run setup-wizard -- --resume |
| Bad saved answers | npm run setup-wizard -- --reset |
| Need to preview generated env files | npm run setup-wizard --dry-run or npm run setup-wizard -- --dry-run |
| Dry-run prints redacted secrets | Add --show-secrets only in a private terminal |
Existing .env.local conflict | Use merge, backup-and-overwrite, overwrite, or abort; --yes defaults to merge |
| Database schema not applied | Paste the contents of supabase/schema.sql into the Supabase SQL Editor, or use Supabase MCP. |
Vitest or build tools fail with spawn EPERM on Windows | Re-run outside the sandbox or with worker spawning permitted |
Error: listen EADDRINUSE: address already in use :::3000
npx kill-port 3000
npm run dev
Requires 20+. node -v. Use nvm use 20 if needed.
rm -rf node_modules package-lock.json
npm install
| Problem | Fix |
|---|
| "Invalid login credentials" | Verify email confirmed in Supabase Auth |
| Magic link not arriving | Check spam, Supabase → Auth → Logs |
| Session not persisting | Verify NEXT_PUBLIC_SUPABASE_URL, test incognito |
| OAuth redirect fails | Add {NEXT_PUBLIC_APP_URL}/auth/callback to provider console |
| OAuth cancel redirects to localhost | Update Site URL in Supabase Dashboard (Auth -> URL Configuration) to your production domain (e.g. https://vibe44.com) |
| Sidebar missing after login | Login must use window.location.href (hard nav) |
| "Auth error" after verify | /verified calls signOut() to clear stale session |
| Duplicate email success | Expected. Check data.user?.identities — empty = exists |
/auth/callback crash | Route parses error params, redirects with toast |
| MFA bypassed via OAuth | proxy.ts checks AAL2, redirects if not met |
| Passkey MFA flash | handlePasskeyLogin() mounts MfaChallenge inline |
| Feature page still accessible | Server-side is[Feature]Enabled() guards |
| Sidebar hydration crash | Stable IDs in Radix tooltips/collapsibles |
| Email verified page shows twice | Server-side OTP action redirects immediately to /verified |
useTranslations crash | Needs NextIntlClientProvider wrapper |
/auth/callback calls exchangeCodeForSession(code)redirectTo: {NEXT_PUBLIC_APP_URL}/auth/callback?next=/reset-password/reset-password NOT in AUTH_ROUTES- After reset:
signOut() to invalidate
| Problem | Fix |
|---|
| "relation does not exist" | npm run db:push |
| RLS blocking queries | Check policies, verify role |
| Drizzle migration errors | npm run db:generate then db:push |
| Standalone index crash | Inside pgTable() third arg (Drizzle #5064) |
| Pool exhausted | Pooled connection (port 6543) |
| Supabase 429 | Client-side caching |
| Avatar upload RLS error | Uses service role client; see api/user/avatar |
| Problem | Fix |
|---|
| Webhook not processing | Verify {PROVIDER}_WEBHOOK_SECRET |
| "Customer not found" | Check stripe_customer_id in profiles |
| Subscription not updating | Enable webhook events in provider dashboard |
| Duplicate subscription/purchase | Confirm the latest provider-resource unique indexes are applied |
| Test → live fails | Switch to live keys, update endpoint URL |
| Creem 401 | Verify CREEM_WEBHOOK_SECRET |
| Creem duplicate retries | Confirm sandbox payloads include durable event.id |
| Dodo orphaned records | syncSubscriptionToDb requires valid userId |
| Sentry not capturing | Verify @sentry/nextjs, providers use captureError() |
| Health false-positive | Check provider-specific env vars |
stripe listen --forward-to localhost:3000/api/webhooks/stripe
ngrok http 3000 # All others
| Problem | Fix |
|---|
| "API key not valid" | Verify GEMINI_API_KEY, enable API |
| Embeddings failing | Ensure @google/genai SDK is up to date |
| Widget not loading | isAiChatEnabled() returns true |
| RAG empty | Re-embed after model change, enable pgvector |
| Mic denied | HTTPS (or localhost), check permissions |
| Audio silent | Check ELEVENLABS_API_KEY, user must interact first |
| Murf audio rejected | Confirm the provider audioFile URL is public HTTPS and passes SSRF checks |
| Problem | Fix |
|---|
| Hydration mismatch | useEffect for dynamic values, suppressHydrationWarning |
| Dark mode broken | bg-background / text-foreground, never hardcoded |
| Card inconsistent | Use GlowCard, not inline glassmorphism |
| Chart colors wrong | CHART_COLORS from @/lib/constants/chart-colors |
| Motion too large | import { m } from "motion/react" |
Empty src warning | AvatarImage normalizes "" to undefined; uses object-cover for 1:1 crop |
| React Compiler loop | useCallback with explicit deps |
| Problem | Fix |
|---|
| Not loading | Verify NEXT_EXTERNAL_ANALYTICS_PROVIDER, provider env vars, and stored analytics consent |
| Mixpanel not tracking | Ensure NEXT_PUBLIC_MIXPANEL_TOKEN is set correctly and consent is granted |
| PostHog not tracking | Host URL must start with https: |
| GA4 ID rejected | Only G- prefix (not UA-) |
| DataFast not loading | Set both NEXT_PUBLIC_DATAFAST_WEBSITE_ID and NEXT_PUBLIC_DATAFAST_DOMAIN |
| Duplicate pageviews | Verify manual page tracking is not duplicated outside AnalyticsProvider |
| SSR hydration | "use client" on analytics components |
| PII leak | trackSignup() excludes email; scripts stay disabled until explicit analytics consent |
| Problem | Fix |
|---|
| Build failing | npm run type-check, verify env vars |
| Vercel env missing | Project Settings → correct environment, redeploy |
| Railway env missing | Variables tab,railway variables CLI |
| CSP errors | proxy.ts nonce-based CSP + strict-dynamic |
| 500 in production | Runtime logs, verify DATABASE_URL + API keys |
| Problem | Fix |
|---|
| Registration fails | Chrome 67+, Firefox 60+, Safari 14+, HTTPS |
| Challenge expired | Complete within 60 seconds |
| "Invalid TOTP" | Sync authenticator clock (30s windows) |
| AAL2 not reached | getAuthenticatorAssuranceLevel() to verify |
| Problem | Fix |
|---|
| Switcher not visible | isI18nEnabled() returns true in lib/config/app.ts |
| Translations not loading | Check locales/frontend/{locale}.ts |
| Wrong namespace | useTranslations('namespace') matches top-level key |
| Cache stale | Remove .next, then run npm run dev |
| Problem | Fix |
|---|
| Not executing | Ensure BACKGROUND_JOBS_PROVIDER is set (qstash or trigger) and correct keys are provided in .env.local. |
| QStash failures | Verify QSTASH_TOKEN, current/next signing keys, and ensure webhook signature verification passes in production. |
| Trigger.dev fail | Verify TRIGGER_SECRET_KEY and TRIGGER_PROJECT_ID are set. |
| Dev disconnected | For Trigger.dev: run npx trigger.dev dev alongside npm run dev. For QStash: use a local tunnel (e.g., ngrok). |
| Failing silently | Check your active provider's dashboard (Upstash QStash schedule history or Trigger.dev Run logs). |
| Problem | Fix |
|---|
/api/rpc/* 404 | Verify app/api/rpc/[...path]/route.ts exists |
| Validation fails | Zod schema matches payload |
| Generic 500 | Use ORPCError("NOT_FOUND") with i18n |
| Wrong base URL | lib/rpc/client.ts derives from config.app.url |
| Namespace miss | Common.serverErrors (not bare serverErrors) |
| Problem | Fix |
|---|
redirect throws | Mock with vi.fn() wrapper |
| Class mock fails | Use function() not arrow |
| Module mock broken | @/lib/... paths match vitest.config.ts aliases |
| Stale mock ref | Wrapper functions, not vi.resetModules() |
db.update() chain | Mock full chain:.set().where() |
getTranslations mismatch | vi.fn().mockImplementation(async () => (key) => key) |
MFA enrollMfa fails | Mock mfa.listFactors() → { totp: [] } |
npm test # All
npm test -- tests/unit/actions/billing.test.ts # Single
npm test -- --reporter=verbose # Verbose
| Problem | Fix |
|---|
Can't access /super-admin/* | role = 'super-admin' in profiles |
| Redirects to dashboard | SUPABASE_SECRET_KEY set |
| Actions not logging | RLS allows super-admin inserts to activity_logs |
| Role change no effect | User must re-login |
Copyright © 2026 Vibe44. Built with ❤️ by Scale with Alap.
