# トラブルシューティング FAQ
SUMMARY: Synapse のよくある問題の解決策 — 認証、ネットワーク、データ、デプロイ。

トラブルシューティング FAQ
Synapse のよくある問題の解決策です。
ログインできない
症状
-  が 401 を返す
- "Invalid email or password"
解決策
1. メールアドレスが正しいか確認 — 大文字小文字を区別
2. パスワードを確認 — 最低 6 文字
3. アカウントがない場合は登録：
4. パスワードリセット（SMTP 構成時）— Web UI 経由
Mind Key を失くした
症状
- メモリにアクセスできない
- Mind Key が削除/紛失
解決策
Mind Key は復元できません。以下を行う必要があります。
1. ログインして JWT を取得：
2. mind を一覧：（JWT で）
3. 新しい mind を作成：
4. 新しい Mind Key を保存
5. （オプション）古い mind を削除：
古い mind のデータは失われます — Mind Key が見つからない限り。
API 呼び出しが 401 を返す
症状
- すべての API 呼び出しが 401 Unauthorized を返す
- "Mind Key fehlt oder ungültig"
解決策
1. ヘッダー形式を確認：
2. Mind Key が  で始まるか確認（ は JWT）
3. 直接テスト：
   [CODE BLOCK]
4. Mind Key が失効している可能性 — 新しい mind を作成
Authentication を参照。
API 呼び出しが 404 を返す
症状
- 404 Not Found
- "Route not found"
解決策
> [!CRITICAL]
> エンドポイントのパスを推測しないでください。 にあるパスのみが存在します。
1. 有効なエンドポイントを確認：
2. URL を正確に比較 — 大文字小文字を区別、末尾スラッシュなし
3. HTTP メソッドを確認 —  と  は異なる
API 呼び出しが 429 を返す
症状
- 429 Too Many Requests
- "Rate limit exceeded"
解決策
1. ヘッダー認証に切り替え（レート制限なし）：
   [CODE BLOCK]
2.  を使う必要がある場合は  秒待機
Rate Limits を参照。
メモリ検索が結果を返さない
症状
-  が空を返す
- メモリが存在することは分かっている
解決策
1. メモリが存在するか確認：
2. 検索構文を確認 — FTS5 には固有の構文があります
3. よりシンプルなクエリを試す —  ではなく 
4. 概念的クエリにはセマンティック検索を使用：
FTS5 Search を参照。
メモリが永続化されない
症状
- POST /memory は成功を返す
- GET /memory/recall に表示されない
解決策
1. 同じ Mind Key か確認 — 異なるキー = 異なる mind
2. レスポンスを確認 — POST は  を返す
3. /memory/recall（テキスト）の代わりに GET /memory（JSON リスト）を試す
4. フィルタを確認 —  や  が隠している可能性
Claude Desktop にツールが表示されない
症状
- Claude Desktop が 0 ツールを表示
- 🔌 アイコンがない
解決策
1. Claude Desktop を完全に再起動（Cmd+Q）
2. 設定ファイルが有効な JSON か確認
3. Node.js 18+ がインストールされているか確認
4. MCP を手動で実行：
5. ログを確認：
MCP Troubleshooting を参照。
Synapse がオフライン
症状
- synapse.schaefer.zone に届かない
- curl がタイムアウト
解決策
1. インターネット接続を確認 — 別のサイトを試す
2. Synapse のヘルスを確認：
3. 待機 — 一時的な停止やデプロイの可能性
4. ステータスページを確認（あれば）
セルフホストの場合：Docker コンテナのステータス、データベース接続を確認。
データベースエラー
症状
- 500 Internal Server Error
- "Database connection failed"
解決策
セルフホストの場合：
1. PostgreSQL が実行中か確認：
2. 環境の DATABASEURL を確認
3. マイグレーションを確認：
4. ディスク容量を確認：
ホスト版の場合：サポートに報告。
Webhook が発火しない
症状
- Webhook を登録したがコールバックを受け取らない
- あなたの URL に POST が来ない
解決策
1. URL が到達可能か確認：
2. events フィルタを確認 —  は全メモリイベントにマッチ
3. Webhook をテスト：
4. Webhook が有効か確認：
5. SSL を確認 — Synapse は Webhook URL に有効な HTTPS を要求
Webhooks API を参照。
Cron ジョブが実行されない
症状
- Cron ジョブを作成したが発火しない
-  が更新されない
解決策
1. スケジュール構文を確認 — 有効な 5 フィールド cron または整数秒である必要
2. エンドポイントが許可されているか確認 — http(s) で、プライベート IP 不可
3. ジョブが有効か確認：
4. 次のスケジュール時刻まで待機 — cron は即時ではない
Cron & Scheduler を参照。
さらにヘルプが必要な場合
1. 既存のドキュメントを確認：<https://synapse.schaefer.zone/docs>
2. ドキュメントを検索：
3. Issue を開く：<https://gitlab.com/schaefer-services/synapse/-/issues>
4. 連絡先： ページを参照
次のステップ
- Errors & Error Handling
- API FAQ
- MCP Troubleshooting