Troubleshooting FAQ

Solutions to common Synapse problems.

I can't login

Symptoms

• POST /login returns 401
• "Invalid email or password"

Solutions

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

I lost my Mind Key

Symptoms

• Cannot access memories
• Mind Key was deleted/lost

Solutions

Mind Keys cannot be recovered. You must:

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

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

API calls return 401

Symptoms

• All API calls return 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Solutions

1. Verify header format: Authorization: Bearer mk_...
2. Check Mind Key starts with mk_ (not eyJ which is JWT)
3. Test directly:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. Mind Key may be revoked — create a new mind

See Authentication.

API calls return 404

Symptoms

• 404 Not Found
• "Route not found"

Solutions

1. Check valid endpoints: curl https://synapse.schaefer.zone/endpoints
2. Compare URL exactly — case sensitive, no trailing slashes
3. Check HTTP method — GET /memory vs POST /memory are different

API calls return 429

Symptoms

• 429 Too Many Requests
• "Rate limit exceeded"

Solutions

1. Switch to header auth (no rate limit):

   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Wait Retry-After seconds if you must use ?key=

See Rate Limits.

Memory search returns no results

Symptoms

• GET /memory/search?q=... returns empty
• Know memories exist

Solutions

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

See FTS5 Search.

Memories are not persisting

Symptoms

• POST /memory returns success
• GET /memory/recall doesn't show them

Solutions

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

Tools not appearing in Claude Desktop

Symptoms

• Claude Desktop shows 0 tools
• No 🔌 icon

Solutions

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

See MCP Troubleshooting.

Synapse is offline

Symptoms

• Cannot reach synapse.schaefer.zone
• curl times out

Solutions

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

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

Database errors

Symptoms

• 500 Internal Server Error
• "Database connection failed"

Solutions

For self-hosted:

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

For hosted: report to support.

Webhook not firing

Symptoms

• Registered webhook but not receiving callbacks
• No POST to your URL

Solutions

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

See Webhooks API.

Cron job not running

Symptoms

• Created cron job but it's not firing
• next_run not updating

Solutions

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

See Cron & Scheduler.

Need More Help?

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

Next Steps

• Errors & Error Handling
• API FAQ
• MCP Troubleshooting