# 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**:
   ```bash
   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](/docs/getting-started/authentication).

## API calls return 404

### Symptoms

- 404 Not Found
- "Route not found"

### Solutions

> [!CRITICAL]
> Don't guess endpoint paths. Only paths in `GET /endpoints` exist.

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):
   ```bash
   # 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](/docs/api/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](/docs/concepts/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](/docs/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](/docs/api/webhooks).

## 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](/docs/api/cron).

## 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](/docs/api/errors)
- [API FAQ](/docs/faq/api-faq)
- [MCP Troubleshooting](/docs/mcp/troubleshooting)