# トラブルシューティング FAQ

Synapse のよくある問題の解決策です。

## ログインできない

### 症状

- `POST /login` が 401 を返す
- "Invalid email or password"

### 解決策

1. **メールアドレスが正しいか確認** — 大文字小文字を区別
2. **パスワードを確認** — 最低 6 文字
3. **アカウントがない場合は登録**：`POST /register`
4. **パスワードリセット**（SMTP 構成時）— Web UI 経由

## Mind Key を失くした

### 症状

- メモリにアクセスできない
- Mind Key が削除/紛失

### 解決策

Mind Key は復元できません。以下を行う必要があります。

1. ログインして JWT を取得：`POST /login`
2. mind を一覧：`GET /minds`（JWT で）
3. 新しい mind を作成：`POST /minds`
4. 新しい Mind Key を保存
5. （オプション）古い mind を削除：`DELETE /minds/:id`

**古い mind のデータは失われます** — Mind Key が見つからない限り。

## API 呼び出しが 401 を返す

### 症状

- すべての API 呼び出しが 401 Unauthorized を返す
- "Mind Key fehlt oder ungültig"

### 解決策

1. **ヘッダー形式を確認**：`Authorization: Bearer mk_...`
2. **Mind Key が `mk_` で始まるか確認**（`eyJ` は JWT）
3. **直接テスト**：
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key が失効している可能性** — 新しい mind を作成

[Authentication](/docs/getting-started/authentication) を参照。

## API 呼び出しが 404 を返す

### 症状

- 404 Not Found
- "Route not found"

### 解決策

> [!CRITICAL]
> エンドポイントのパスを推測しないでください。`GET /endpoints` にあるパスのみが存在します。

1. **有効なエンドポイントを確認**：`curl https://synapse.schaefer.zone/endpoints`
2. **URL を正確に比較** — 大文字小文字を区別、末尾スラッシュなし
3. **HTTP メソッドを確認** — `GET /memory` と `POST /memory` は異なる

## API 呼び出しが 429 を返す

### 症状

- 429 Too Many Requests
- "Rate limit exceeded"

### 解決策

1. **ヘッダー認証に切り替え**（レート制限なし）：
   ```bash
   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **`?key=` を使う必要がある場合は `Retry-After` 秒待機**

[Rate Limits](/docs/api/rate-limits) を参照。

## メモリ検索が結果を返さない

### 症状

- `GET /memory/search?q=...` が空を返す
- メモリが存在することは分かっている

### 解決策

1. **メモリが存在するか確認**：`GET /memory/recall`
2. **検索構文を確認** — FTS5 には固有の構文があります
3. **よりシンプルなクエリを試す** — `?q=docker+swarm+deployment` ではなく `?q=docker`
4. **概念的クエリにはセマンティック検索を使用**：`GET /memory/semantic-search?q=...`

[FTS5 Search](/docs/concepts/fts5-search) を参照。

## メモリが永続化されない

### 症状

- POST /memory は成功を返す
- GET /memory/recall に表示されない

### 解決策

1. **同じ Mind Key か確認** — 異なるキー = 異なる mind
2. **レスポンスを確認** — POST は `{ "id": "mem_...", "status": "stored" }` を返す
3. **/memory/recall（テキスト）の代わりに GET /memory（JSON リスト）を試す**
4. **フィルタを確認** — `?category=` や `?tag=` が隠している可能性

## Claude Desktop にツールが表示されない

### 症状

- Claude Desktop が 0 ツールを表示
- 🔌 アイコンがない

### 解決策

1. **Claude Desktop を完全に再起動**（Cmd+Q）
2. **設定ファイルが有効な JSON か確認**
3. **Node.js 18+ がインストールされているか確認**
4. **MCP を手動で実行**：`npx -y synapse-mcp-api@latest`
5. **ログを確認**：`~/Library/Logs/Claude/mcp.log`

[MCP Troubleshooting](/docs/mcp/troubleshooting) を参照。

## Synapse がオフライン

### 症状

- synapse.schaefer.zone に届かない
- curl がタイムアウト

### 解決策

1. **インターネット接続を確認** — 別のサイトを試す
2. **Synapse のヘルスを確認**：`curl https://synapse.schaefer.zone/health`
3. **待機** — 一時的な停止やデプロイの可能性
4. **ステータスページを確認**（あれば）

セルフホストの場合：Docker コンテナのステータス、データベース接続を確認。

## データベースエラー

### 症状

- 500 Internal Server Error
- "Database connection failed"

### 解決策

セルフホストの場合：

1. **PostgreSQL が実行中か確認**：`docker ps | grep postgres`
2. **環境の DATABASE_URL を確認**
3. **マイグレーションを確認**：`npm run migrate:check`
4. **ディスク容量を確認**：`df -h`

ホスト版の場合：サポートに報告。

## Webhook が発火しない

### 症状

- Webhook を登録したがコールバックを受け取らない
- あなたの URL に POST が来ない

### 解決策

1. **URL が到達可能か確認**：`curl -X POST your-url -d '{}'`
2. **events フィルタを確認** — `memory.*` は全メモリイベントにマッチ
3. **Webhook をテスト**：`POST /webhooks/:id/test`
4. **Webhook が有効か確認**：`GET /webhooks/:id`
5. **SSL を確認** — Synapse は Webhook URL に有効な HTTPS を要求

[Webhooks API](/docs/api/webhooks) を参照。

## Cron ジョブが実行されない

### 症状

- Cron ジョブを作成したが発火しない
- `next_run` が更新されない

### 解決策

1. **スケジュール構文を確認** — 有効な 5 フィールド cron または整数秒である必要
2. **エンドポイントが許可されているか確認** — http(s) で、プライベート IP 不可
3. **ジョブが有効か確認**：`GET /cron`
4. **次のスケジュール時刻まで待機** — cron は即時ではない

[Cron & Scheduler](/docs/api/cron) を参照。

## さらにヘルプが必要な場合

1. **既存のドキュメントを確認**：<https://synapse.schaefer.zone/docs>
2. **ドキュメントを検索**：`GET /docs/search?q=your+question`
3. **Issue を開く**：<https://gitlab.com/schaefer-services/synapse/-/issues>
4. **連絡先**：`/support` ページを参照

## 次のステップ

- [Errors & Error Handling](/docs/api/errors)
- [API FAQ](/docs/faq/api-faq)
- [MCP Troubleshooting](/docs/mcp/troubleshooting)