トラブルシューティング 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. 直接テスト：

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

4. Mind Key が失効している可能性 — 新しい mind を作成

Authentication を参照。

API 呼び出しが 404 を返す

症状

• 404 Not Found
• "Route not found"

解決策

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. ヘッダー認証に切り替え（レート制限なし）：

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

2. ?key= を使う必要がある場合は Retry-After 秒待機

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 を参照。

メモリが永続化されない

症状

• 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 を参照。

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 を参照。

Cron ジョブが実行されない

症状

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

解決策

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

Cron & Scheduler を参照。

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

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
• API FAQ
• MCP Troubleshooting