> Markdown export: /developers/troubleshooting.md
> HTML: /developers/troubleshooting
---
description: Common problems and fixes for managed users and self-hosted operators — signup, billing, deployment, MCP, and encryption help.
audience: operator
---

# 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](/developers/self-hosted-setup) |
| 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)](/developers/onboarding-managed) or [What is Eigen Mesh?](/developers/what-is-eigenmesh).

## Deployment

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| App container exits on start | Missing `BETTER_AUTH_SECRET`, `TENANT_MASTER_KEY`, or LLM vars | Set [required environment variables](/developers/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](/developers/cursor-and-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](/developers/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?

1. Check **Activity** in the product UI for per-call error detail.
2. Review app container logs: `docker compose logs app`
3. Review DB logs: `docker compose logs db`
4. See [Upgrades & backups](/developers/upgrades-and-backups) before destructive changes.

## Next steps

- [What is Eigen Mesh?](/developers/what-is-eigenmesh)
- [Environment variables](/developers/environment-variables)
- [Overview & quick start](/developers/getting-started)
- [MCP overview](/developers/mcp-overview)