Skip to content

Troubleshooting & FAQ

Fixes for the most common problems, in the order you're likely to hit them. All paths and ports below assume the one-line installer (~/.membrain, gateway on http://localhost:8001). If you run from source with Docker Compose, substitute your own ports.

Quick diagnostics

Before anything else, these three commands tell you what state MemBrain is in:

membrain status                      # container health at a glance
curl http://localhost:8001/health    # gateway liveness
membrain logs                        # recent gateway logs

Installation problems

"Unsupported platform"

The installer supports macOS 13 (Ventura) or later, and Linux. Older macOS versions are not supported.

"Docker Compose plugin not found" / Docker won't start

MemBrain runs as Docker containers. Install Docker Desktop (macOS) or the docker-compose-plugin package (Linux), start it, and re-run the installer. The installer waits up to 90 seconds for the Docker daemon — if it times out, start Docker manually first.

"Port 8001 is already in use"

Another service is bound to the gateway's port. Find it with lsof -i :8001, stop it, and re-run the installer.

Install finished but the gateway isn't responding

The containers can take a little while on first start (image pulls, database migrations). Check progress with:

membrain logs

If the log shows a crash rather than startup progress, the error message at the bottom is almost always the actual cause — read it before anything else.

First request fails

401 "Missing API key"

Authentication is on (REQUIRE_AUTH=true, the default for network-exposed installs). Requests need a MemBrain key, passed either way:

-H "X-Membrain-Api-Key: ck_live_..."
# or
-H "Authorization: Bearer ck_live_..."

See the Quickstart for creating keys.

Provider errors: "no API key" / authentication failed upstream

MemBrain forwards requests to the providers you configure, and the installer lets you skip adding a key. Add your provider keys to ~/.membrain/.env:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

then restart with membrain stop && membrain start.

Exception: Claude Code with ANTHROPIC_BASE_URL=http://localhost:8001 needs no key in .env — its own login session is forwarded upstream.

502 / 504 errors

The gateway couldn't reach the upstream provider (502) or the request timed out (504). Check your network and the provider's status page, then retry.

Runtime issues

429 "rate limited" — two different causes

From your provider (passed through). MemBrain forwards the provider's own rate-limit responses faithfully, including the retry-after header and (for Anthropic) anthropic-ratelimit-* reset metadata. A subscription-based client like Claude Code hitting its usage cap will see 429s through MemBrain exactly as it would without it — often per model, so switching model can help while a cap resets. Nothing in MemBrain causes or fixes these; the cap resets on the provider's schedule.

From MemBrain itself. If you configured per-key rate limits (RATE_LIMIT_RPM), exceeding them returns 429 with a Retry-After header. A 402 means a configured budget (BUDGET_LIMIT_USD) was exceeded.

PII redaction is too aggressive (or not aggressive enough)

Detection confidence is tunable. In ~/.membrain/.env:

PII_MIN_CONFIDENCE=0.5   # raise toward 1.0 for fewer, higher-confidence redactions

See Configuration for per-pattern control.

Knowledge search returns nothing

Semantic search needs the embeddings add-on:

membrain enable ml-search

Without it (and Postgres), knowledge features are limited or disabled.

My data disappeared after a restart

Without a configured database, the gateway runs on an in-memory fallback — fine for trying it out, but nothing persists. The installer's default stack includes Postgres; if you run from source, set DATABASE_URL (see Configuration).

FAQ

Does my data leave my machine? MemBrain is fully self-hosted. The only outbound traffic is to the LLM providers you configure (and only after PII sanitization). Route to a local model via Ollama and nothing leaves your machine at all.

What's free and what's paid? The Community build — proxy, shared memory, PII detection, routing, dashboard, audit trail — is free and open source (Apache 2.0). Team and Enterprise features (team queue, SSO, ML-based NER, SIEM export) require a license. See pricing.

Does MemBrain slow my requests down? Some, honestly. Regex-based PII scanning adds little. Semantic memory lookup adds an embedding query per request when enabled, and injected knowledge adds prompt tokens (visible in the dashboard). If a request path feels slow, membrain logs includes per-request timing.

What does MemBrain capture? Every proxied exchange and tool call is stored as a bounded, PII-sanitized episode, private to its owner, kept 90 days by default; capture is forward-only and sanitization failure drops the capture rather than storing raw text.

How does memory review work? Deliberate saves and daily reflected lessons (at most eight per day, each citing the episodes it derives from) land in a pending queue — nothing is injected until a human approves it. Rejected entries are tombstoned so the same content isn't re-proposed.

How do I upgrade?

membrain update

How do I uninstall?

membrain uninstall

This removes the containers and ~/.membrain. Your data is in the Postgres volume — export first via the dashboard if you want to keep it.

Which providers are supported? Anthropic, OpenAI, Claude CLI, and Ollama natively; 100+ more via the LiteLLM add-on (membrain enable litellm). See Providers.

Still stuck?