Troubleshooting
In plain terms: Common problems and fixes — whether you use managed hosting or run your own server. Start here when you are stuck, need help, or something is broken.
Who this is for
- End users on managed hosting with billing or capture issues
- Operators debugging self-hosted deployment, MCP, or encryption problems
Managed users
| Symptom |
Likely cause |
Fix |
| Capture fails — insufficient credits |
Free credits exhausted or no active subscription |
Settings → LLM — subscribe (€3.99/mo) or configure BYOK |
| Capture fails — LLM not configured |
Empty wallet (platform credits) or missing BYOK keys |
Settings → LLM — subscribe, or configure BYOK |
| Subscribe / billing option missing |
Subscription checkout not enabled yet |
Contact support, use BYOK, or self-host |
| BYOK option disabled |
No provider saved in Settings → LLM → BYOK |
Save EUrouter or OpenRouter credentials first |
| Welcome tour does not appear |
Already completed or skipped |
Settings → Onboarding → Restart onboarding |
| OAuth sign-in fails |
Provider not enabled on this deployment |
Use email/password or ask the operator |
New to Eigen Mesh? See Onboarding (managed) or What is Eigen Mesh?.
Deployment
| Symptom |
Likely cause |
Fix |
| App container exits on start |
Missing BETTER_AUTH_SECRET, TENANT_MASTER_KEY, or LLM vars |
Set required environment variables |
| Database connection refused |
db container not ready or wrong DATABASE_URL |
Wait for health; use postgres://eigen:eigen@db:5432/eigen inside compose |
| 500 on first request after deploy |
Schema or RLS not applied |
Run npm run db:push:force && npm run db:rls in eigen repo |
| Coolify deploy green but app 502 |
Migrations not run |
Execute Command on app container: npx drizzle-kit push --force && node scripts/apply-rls.mjs |
| Postgres port conflict on host |
Default 5432:5432 mapping |
Change ports in docker-compose.yaml |
LLM and billing
| Symptom |
Likely cause |
Fix |
| Capture fails — LLM not configured |
Empty wallet (platform credits), no subscription, or missing BYOK keys |
Settings → LLM — subscribe, add credits (self-hosted operator), or configure BYOK |
| All LLM calls fail after 3 retries |
Gateway down, wrong LLM_BASE_URL, or invalid rule UUIDs |
Verify gateway credentials and LLM_RULE_CHAT / LLM_RULE_EMBEDDING |
| PayPal button missing (self-hosted wallet top-ups) |
PAYPAL_* env vars not set |
Configure PayPal for operator credit packs, or switch users to BYOK |
| BYOK option disabled |
No provider saved in Settings → LLM → BYOK |
Save EUrouter or OpenRouter credentials first |
MCP integration
| Symptom |
Likely cause |
Fix |
| 401 Unauthorized |
Invalid or revoked API key |
Regenerate at /api-keys; update client config |
| Tools not appearing in client |
MCP server disabled or wrong URL |
Verify https://<origin>/api/mcp — see Connect Cursor or Claude |
| Empty search results |
No captured thoughts yet, or query too narrow |
Capture test thoughts; try broader queries |
| Connection refused (local) |
App not running on expected port |
Confirm docker compose ps; default port 3000 |
Auth and encryption
| Symptom |
Likely cause |
Fix |
| OAuth sign-in fails |
Callback URL mismatch |
Must be {ORIGIN}/api/auth/callback/<provider> |
| Encrypt/decrypt errors |
TENANT_MASTER_KEY missing or rotated without migration |
See Tenant envelope encryption |
| New users work, old users fail |
Key rotation without re-encryption |
Restore key or run re-encryption migration |
Retrieval
| Symptom |
Likely cause |
Fix |
| Unexpected ranking |
Retrieval uses weighted merge + LLM rerank over precomputed neighbors |
Try a more specific query; inspect matches with retrieve_thoughts |
| Grounded answer misses context |
Query doesn't match stored wording |
Try retrieve_thoughts with alternate phrasing before composing |
| Theme-level questions weak |
Global retrieval deferred |
Expected for MVP — corpus-wide synthesis not wired |
Still stuck?
- Check Activity in the product UI for per-call error detail.
- Review app container logs:
docker compose logs app
- Review DB logs:
docker compose logs db
- See Upgrades & backups before destructive changes.
Next steps
