# Troubleshooting FAQ
SUMMARY: Solutions to common Synapse problems — auth, network, data, deployment.

Troubleshooting FAQ
Solutions to common Synapse problems.
I can't login
Symptoms
-  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: 
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: 
2. List minds:  (with JWT)
3. Create new mind: 
4. Save new Mind Key
5. (Optional) Delete old mind: 
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: 
2. Check Mind Key starts with  (not  which is JWT)
3. Test directly:
   [CODE BLOCK]
4. Mind Key may be revoked — create a new mind
See Authentication.
API calls return 404
Symptoms
- 404 Not Found
- "Route not found"
Solutions
> [!CRITICAL]
> Don't guess endpoint paths. Only paths in  exist.
1. Check valid endpoints: 
2. Compare URL exactly — case sensitive, no trailing slashes
3. Check HTTP method —  vs  are different
API calls return 429
Symptoms
- 429 Too Many Requests
- "Rate limit exceeded"
Solutions
1. Switch to header auth (no rate limit):
   [CODE BLOCK]
2. Wait  seconds if you must use 
See Rate Limits.
Memory search returns no results
Symptoms
-  returns empty
- Know memories exist
Solutions
1. Verify memories exist: 
2. Check search syntax — FTS5 has specific syntax
3. Try simpler query —  instead of 
4. Use semantic search for conceptual queries: 
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 
3. Try GET /memory (JSON list) instead of /memory/recall (text)
4. Check filter —  or  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: 
5. Check logs: 
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: 
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: 
2. Check DATABASEURL in env
3. Check migrations: 
4. Check disk space: 
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: 
2. Check events filter —  matches all memory events
3. Test webhook: 
4. Check webhook is enabled: 
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
-  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: 
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: 
3. Open issue: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. Contact: see  page
Next Steps
- Errors & Error Handling
- API FAQ
- MCP Troubleshooting