{"title":"Troubleshooting FAQ","slug":"troubleshooting","category":"faq","summary":"Solutions to common Synapse problems — auth, network, data, deployment.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":622,"read_minutes":3,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Troubleshooting FAQ\n\nSolutions to common Synapse problems.\n\n## I can't login\n\n### Symptoms\n\n- `POST /login` returns 401\n- \"Invalid email or password\"\n\n### Solutions\n\n1. **Verify email is correct** — case sensitive\n2. **Check password** — minimum 6 characters\n3. **Register first** if you don't have an account: `POST /register`\n4. **Reset password** (if SMTP configured) via the web UI\n\n## I lost my Mind Key\n\n### Symptoms\n\n- Cannot access memories\n- Mind Key was deleted/lost\n\n### Solutions\n\nMind Keys cannot be recovered. You must:\n\n1. Login to get JWT: `POST /login`\n2. List minds: `GET /minds` (with JWT)\n3. Create new mind: `POST /minds`\n4. Save new Mind Key\n5. (Optional) Delete old mind: `DELETE /minds/:id`\n\n**Data in the old mind is lost** unless you can find the Mind Key.\n\n## API calls return 401\n\n### Symptoms\n\n- All API calls return 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Solutions\n\n1. **Verify header format**: `Authorization: Bearer mk_...`\n2. **Check Mind Key starts with `mk_`** (not `eyJ` which is JWT)\n3. **Test directly**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key may be revoked** — create a new mind\n\nSee [Authentication](/docs/getting-started/authentication).\n\n## API calls return 404\n\n### Symptoms\n\n- 404 Not Found\n- \"Route not found\"\n\n### Solutions\n\n> [!CRITICAL]\n> Don't guess endpoint paths. Only paths in `GET /endpoints` exist.\n\n1. **Check valid endpoints**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Compare URL exactly** — case sensitive, no trailing slashes\n3. **Check HTTP method** — `GET /memory` vs `POST /memory` are different\n\n## API calls return 429\n\n### Symptoms\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Solutions\n\n1. **Switch to header auth** (no rate limit):\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Wait `Retry-After` seconds** if you must use `?key=`\n\nSee [Rate Limits](/docs/api/rate-limits).\n\n## Memory search returns no results\n\n### Symptoms\n\n- `GET /memory/search?q=...` returns empty\n- Know memories exist\n\n### Solutions\n\n1. **Verify memories exist**: `GET /memory/recall`\n2. **Check search syntax** — FTS5 has specific syntax\n3. **Try simpler query** — `?q=docker` instead of `?q=docker+swarm+deployment`\n4. **Use semantic search** for conceptual queries: `GET /memory/semantic-search?q=...`\n\nSee [FTS5 Search](/docs/concepts/fts5-search).\n\n## Memories are not persisting\n\n### Symptoms\n\n- POST /memory returns success\n- GET /memory/recall doesn't show them\n\n### Solutions\n\n1. **Verify same Mind Key** — different keys = different minds\n2. **Check response** — POST returns `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Try GET /memory** (JSON list) instead of /memory/recall (text)\n4. **Check filter** — `?category=` or `?tag=` may be hiding them\n\n## Tools not appearing in Claude Desktop\n\n### Symptoms\n\n- Claude Desktop shows 0 tools\n- No 🔌 icon\n\n### Solutions\n\n1. **Restart Claude Desktop fully** (Cmd+Q)\n2. **Verify config file** is valid JSON\n3. **Check Node.js 18+** installed\n4. **Run MCP manually**: `npx -y synapse-mcp-api@latest`\n5. **Check logs**: `~/Library/Logs/Claude/mcp.log`\n\nSee [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## Synapse is offline\n\n### Symptoms\n\n- Cannot reach synapse.schaefer.zone\n- curl times out\n\n### Solutions\n\n1. **Check your internet** — try another site\n2. **Check Synapse health**: `curl https://synapse.schaefer.zone/health`\n3. **Wait** — may be temporary outage or deployment\n4. **Check status page** (if available)\n\nFor self-hosted: check Docker container status, database connection.\n\n## Database errors\n\n### Symptoms\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Solutions\n\nFor self-hosted:\n\n1. **Check PostgreSQL running**: `docker ps | grep postgres`\n2. **Check DATABASE_URL** in env\n3. **Check migrations**: `npm run migrate:check`\n4. **Check disk space**: `df -h`\n\nFor hosted: report to support.\n\n## Webhook not firing\n\n### Symptoms\n\n- Registered webhook but not receiving callbacks\n- No POST to your URL\n\n### Solutions\n\n1. **Verify URL is reachable**: `curl -X POST your-url -d '{}'`\n2. **Check events filter** — `memory.*` matches all memory events\n3. **Test webhook**: `POST /webhooks/:id/test`\n4. **Check webhook is enabled**: `GET /webhooks/:id`\n5. **Verify SSL** — Synapse requires valid HTTPS for webhook URLs\n\nSee [Webhooks API](/docs/api/webhooks).\n\n## Cron job not running\n\n### Symptoms\n\n- Created cron job but it's not firing\n- `next_run` not updating\n\n### Solutions\n\n1. **Check schedule syntax** — must be valid 5-field cron OR integer seconds\n2. **Verify endpoint is allowed** — must be http(s), no private IPs\n3. **Check job is enabled**: `GET /cron`\n4. **Wait for next scheduled time** — cron isn't instant\n\nSee [Cron & Scheduler](/docs/api/cron).\n\n## Need More Help?\n\n1. **Check existing docs**: \n2. **Search docs**: `GET /docs/search?q=your+question`\n3. **Open issue**: \n4. **Contact**: see `/support` page\n\n## Next Steps\n\n- [Errors & Error Handling](/docs/api/errors)\n- [API FAQ](/docs/faq/api-faq)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

Troubleshooting FAQ

\n

Solutions to common Synapse problems.

\n

I can't login

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Verify email is correct — case sensitive
    2. \n
  2. Check password — minimum 6 characters
    3. \n
  3. Register first if you don't have an account: POST /register
    4. \n
  4. Reset password (if SMTP configured) via the web UI
    5. \n
\n

I lost my Mind Key

\n

Symptoms

\n\n

Solutions

\n

Mind Keys cannot be recovered. You must:

\n
    \n
  1. Login to get JWT: POST /login
    2. \n
  2. List minds: GET /minds (with JWT)
    3. \n
  3. Create new mind: POST /minds
    4. \n
  4. Save new Mind Key
    5. \n
  5. (Optional) Delete old mind: DELETE /minds/:id
    6. \n
\n

Data in the old mind is lost unless you can find the Mind Key.

\n

API calls return 401

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Verify header format: Authorization: Bearer mk_...
    2. \n
  2. Check Mind Key starts with mk_ (not eyJ which is JWT)
    3. \n
  3. Test directly:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key may be revoked — create a new mind
    5. \n
\n

See Authentication.

\n

API calls return 404

\n

Symptoms

\n\n

Solutions

\n
Don't guess endpoint paths. Only paths in `GET /endpoints` exist.
    \n
  1. Check valid endpoints: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Compare URL exactly — case sensitive, no trailing slashes
    3. \n
  3. Check HTTP method — GET /memory vs POST /memory are different
    4. \n
\n

API calls return 429

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Switch to header auth (no rate limit):
    # Don't\ncurl ".../memory/recall?key=mk_..."\n\n# Do\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Wait Retry-After seconds if you must use ?key=
    3. \n
\n

See Rate Limits.

\n

Memory search returns no results

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Verify memories exist: GET /memory/recall
    2. \n
  2. Check search syntax — FTS5 has specific syntax
    3. \n
  3. Try simpler query — ?q=docker instead of ?q=docker+swarm+deployment
    4. \n
  4. Use semantic search for conceptual queries: GET /memory/semantic-search?q=...
    5. \n
\n

See FTS5 Search.

\n

Memories are not persisting

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Verify same Mind Key — different keys = different minds
    2. \n
  2. Check response — POST returns { "id": "mem_...", "status": "stored" }
    3. \n
  3. Try GET /memory (JSON list) instead of /memory/recall (text)
    4. \n
  4. Check filter — ?category= or ?tag= may be hiding them
    5. \n
\n

Tools not appearing in Claude Desktop

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Restart Claude Desktop fully (Cmd+Q)
    2. \n
  2. Verify config file is valid JSON
    3. \n
  3. Check Node.js 18+ installed
    4. \n
  4. Run MCP manually: npx -y synapse-mcp-api@latest
    5. \n
  5. Check logs: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

See MCP Troubleshooting.

\n

Synapse is offline

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Check your internet — try another site
    2. \n
  2. Check Synapse health: curl https://synapse.schaefer.zone/health
    3. \n
  3. Wait — may be temporary outage or deployment
    4. \n
  4. Check status page (if available)
    5. \n
\n

For self-hosted: check Docker container status, database connection.

\n

Database errors

\n

Symptoms

\n\n

Solutions

\n

For self-hosted:

\n
    \n
  1. Check PostgreSQL running: docker ps | grep postgres
    2. \n
  2. Check DATABASE_URL in env
    3. \n
  3. Check migrations: npm run migrate:check
    4. \n
  4. Check disk space: df -h
    5. \n
\n

For hosted: report to support.

\n

Webhook not firing

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Verify URL is reachable: curl -X POST your-url -d '{}'
    2. \n
  2. Check events filter — memory.* matches all memory events
    3. \n
  3. Test webhook: POST /webhooks/:id/test
    4. \n
  4. Check webhook is enabled: GET /webhooks/:id
    5. \n
  5. Verify SSL — Synapse requires valid HTTPS for webhook URLs
    6. \n
\n

See Webhooks API.

\n

Cron job not running

\n

Symptoms

\n\n

Solutions

\n
    \n
  1. Check schedule syntax — must be valid 5-field cron OR integer seconds
    2. \n
  2. Verify endpoint is allowed — must be http(s), no private IPs
    3. \n
  3. Check job is enabled: GET /cron
    4. \n
  4. Wait for next scheduled time — cron isn't instant
    5. \n
\n

See Cron & Scheduler.

\n

Need More Help?

\n
    \n
  1. Check existing docs: https://synapse.schaefer.zone/docs
    2. \n
  2. Search docs: GET /docs/search?q=your+question
    3. \n
  3. Open issue: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Contact: see /support page
    5. \n
\n

Next Steps

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}