Skip to main content
This page covers the most common issues developers encounter. For setup-specific problems, see the Quickstart troubleshooting section.

​
Common issues

​
Backend won’t start

Symptom: dotnet run fails or API returns 500 on all requests. Causes and fixes:

​
JWT authentication fails (401)

Symptom: All authenticated endpoints return 401. Debug steps:
  1. Check the JWT token is being sent: Authorization: Bearer <token>
  2. Verify token is not expired (Supabase tokens expire after 1 hour by default)
  3. Check JWT_SECRET matches your Supabase project
  4. In dev without JWT_SECRET, the backend bypasses signature validation (warning logged)
  5. Check backend logs for JWT authentication failed or JWT Challenge messages

​
FK violation on thread/comparison creation

Symptom: INSERT INTO threads or INSERT INTO comparisons fails with foreign key error. Root cause: The public.users row doesn’t exist. Supabase Auth creates users in auth.users but not in public.users. Fix: The backend calls UserSyncService.EnsureUserExistsAsync() before any FK-dependent operation. If this is failing, check:
  • The Supabase service role key has permission to insert into public.users
  • The JWT sub claim contains a valid UUID

​
AI provider errors

Symptom: Chat requests return API_ERROR.

​
Frontend can’t connect to backend

Symptom: Network errors in browser console, “Backend unavailable” messages. Fix:
  1. Verify backend is running: curl http://localhost:5079/health
  2. Check config.js — apiBaseUrl should be http://localhost:5079 for local dev
  3. Check CORS — backend allows all origins in dev (AllowAll policy)
  4. Check browser console for specific error messages

​
Streaming not working

Symptom: Chat responses arrive all at once instead of streaming. Causes:
  • Backend: Ensure Content-Type: text/event-stream is set on the response
  • Frontend: Must use fetch() with ReadableStream, not EventSource (POST body required)
  • Proxy: Some proxies buffer SSE responses. Cloudflare Workers pass through correctly.
  • Config: Check window.DUALMIND_CONFIG.streaming.enabled === true

​
Debug strategies

​
Backend logging

The backend logs every request with correlation ID:
Check the X-Correlation-Id response header to trace requests through logs.

​
Supabase dashboard

Use the Supabase dashboard to:
  • Table Editor: Inspect data in all tables
  • SQL Editor: Run queries directly
  • Auth: Check user sessions and tokens
  • Logs: View PostgREST and Auth logs

​
Frontend debugging

Enable debug mode in config.js:

​
Error code reference