{"title":"トラブルシューティング FAQ","slug":"troubleshooting","category":"faq","summary":"Synapse のよくある問題の解決策 — 認証、ネットワーク、データ、デプロイ。","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":418,"read_minutes":2,"lang":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# トラブルシューティング FAQ\n\nSynapse のよくある問題の解決策です。\n\n## ログインできない\n\n### 症状\n\n- `POST /login` が 401 を返す\n- \"Invalid email or password\"\n\n### 解決策\n\n1. **メールアドレスが正しいか確認** — 大文字小文字を区別\n2. **パスワードを確認** — 最低 6 文字\n3. **アカウントがない場合は登録**：`POST /register`\n4. **パスワードリセット**（SMTP 構成時）— Web UI 経由\n\n## Mind Key を失くした\n\n### 症状\n\n- メモリにアクセスできない\n- Mind Key が削除/紛失\n\n### 解決策\n\nMind Key は復元できません。以下を行う必要があります。\n\n1. ログインして JWT を取得：`POST /login`\n2. mind を一覧：`GET /minds`（JWT で）\n3. 新しい mind を作成：`POST /minds`\n4. 新しい Mind Key を保存\n5. （オプション）古い mind を削除：`DELETE /minds/:id`\n\n**古い mind のデータは失われます** — Mind Key が見つからない限り。\n\n## API 呼び出しが 401 を返す\n\n### 症状\n\n- すべての API 呼び出しが 401 Unauthorized を返す\n- \"Mind Key fehlt oder ungültig\"\n\n### 解決策\n\n1. **ヘッダー形式を確認**：`Authorization: Bearer mk_...`\n2. **Mind Key が `mk_` で始まるか確認**（`eyJ` は JWT）\n3. **直接テスト**：\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key が失効している可能性** — 新しい mind を作成\n\n[Authentication](/docs/getting-started/authentication) を参照。\n\n## API 呼び出しが 404 を返す\n\n### 症状\n\n- 404 Not Found\n- \"Route not found\"\n\n### 解決策\n\n> [!CRITICAL]\n> エンドポイントのパスを推測しないでください。`GET /endpoints` にあるパスのみが存在します。\n\n1. **有効なエンドポイントを確認**：`curl https://synapse.schaefer.zone/endpoints`\n2. **URL を正確に比較** — 大文字小文字を区別、末尾スラッシュなし\n3. **HTTP メソッドを確認** — `GET /memory` と `POST /memory` は異なる\n\n## API 呼び出しが 429 を返す\n\n### 症状\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### 解決策\n\n1. **ヘッダー認証に切り替え**（レート制限なし）：\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **`?key=` を使う必要がある場合は `Retry-After` 秒待機**\n\n[Rate Limits](/docs/api/rate-limits) を参照。\n\n## メモリ検索が結果を返さない\n\n### 症状\n\n- `GET /memory/search?q=...` が空を返す\n- メモリが存在することは分かっている\n\n### 解決策\n\n1. **メモリが存在するか確認**：`GET /memory/recall`\n2. **検索構文を確認** — FTS5 には固有の構文があります\n3. **よりシンプルなクエリを試す** — `?q=docker+swarm+deployment` ではなく `?q=docker`\n4. **概念的クエリにはセマンティック検索を使用**：`GET /memory/semantic-search?q=...`\n\n[FTS5 Search](/docs/concepts/fts5-search) を参照。\n\n## メモリが永続化されない\n\n### 症状\n\n- POST /memory は成功を返す\n- GET /memory/recall に表示されない\n\n### 解決策\n\n1. **同じ Mind Key か確認** — 異なるキー = 異なる mind\n2. **レスポンスを確認** — POST は `{ \"id\": \"mem_...\", \"status\": \"stored\" }` を返す\n3. **/memory/recall（テキスト）の代わりに GET /memory（JSON リスト）を試す**\n4. **フィルタを確認** — `?category=` や `?tag=` が隠している可能性\n\n## Claude Desktop にツールが表示されない\n\n### 症状\n\n- Claude Desktop が 0 ツールを表示\n- 🔌 アイコンがない\n\n### 解決策\n\n1. **Claude Desktop を完全に再起動**（Cmd+Q）\n2. **設定ファイルが有効な JSON か確認**\n3. **Node.js 18+ がインストールされているか確認**\n4. **MCP を手動で実行**：`npx -y synapse-mcp-api@latest`\n5. **ログを確認**：`~/Library/Logs/Claude/mcp.log`\n\n[MCP Troubleshooting](/docs/mcp/troubleshooting) を参照。\n\n## Synapse がオフライン\n\n### 症状\n\n- synapse.schaefer.zone に届かない\n- curl がタイムアウト\n\n### 解決策\n\n1. **インターネット接続を確認** — 別のサイトを試す\n2. **Synapse のヘルスを確認**：`curl https://synapse.schaefer.zone/health`\n3. **待機** — 一時的な停止やデプロイの可能性\n4. **ステータスページを確認**（あれば）\n\nセルフホストの場合：Docker コンテナのステータス、データベース接続を確認。\n\n## データベースエラー\n\n### 症状\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### 解決策\n\nセルフホストの場合：\n\n1. **PostgreSQL が実行中か確認**：`docker ps | grep postgres`\n2. **環境の DATABASE_URL を確認**\n3. **マイグレーションを確認**：`npm run migrate:check`\n4. **ディスク容量を確認**：`df -h`\n\nホスト版の場合：サポートに報告。\n\n## Webhook が発火しない\n\n### 症状\n\n- Webhook を登録したがコールバックを受け取らない\n- あなたの URL に POST が来ない\n\n### 解決策\n\n1. **URL が到達可能か確認**：`curl -X POST your-url -d '{}'`\n2. **events フィルタを確認** — `memory.*` は全メモリイベントにマッチ\n3. **Webhook をテスト**：`POST /webhooks/:id/test`\n4. **Webhook が有効か確認**：`GET /webhooks/:id`\n5. **SSL を確認** — Synapse は Webhook URL に有効な HTTPS を要求\n\n[Webhooks API](/docs/api/webhooks) を参照。\n\n## Cron ジョブが実行されない\n\n### 症状\n\n- Cron ジョブを作成したが発火しない\n- `next_run` が更新されない\n\n### 解決策\n\n1. **スケジュール構文を確認** — 有効な 5 フィールド cron または整数秒である必要\n2. **エンドポイントが許可されているか確認** — http(s) で、プライベート IP 不可\n3. **ジョブが有効か確認**：`GET /cron`\n4. **次のスケジュール時刻まで待機** — cron は即時ではない\n\n[Cron & Scheduler](/docs/api/cron) を参照。\n\n## さらにヘルプが必要な場合\n\n1. **既存のドキュメントを確認**：\n2. **ドキュメントを検索**：`GET /docs/search?q=your+question`\n3. **Issue を開く**：\n4. **連絡先**：`/support` ページを参照\n\n## 次のステップ\n\n- [Errors & Error Handling](/docs/api/errors)\n- [API FAQ](/docs/faq/api-faq)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

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

\n

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

\n

ログインできない

\n

症状

\n\n

解決策

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

Mind Key を失くした

\n

症状

\n\n

解決策

\n

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

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

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

\n

API 呼び出しが 401 を返す

\n

症状

\n\n

解決策

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

Authentication を参照。

\n

API 呼び出しが 404 を返す

\n

症状

\n\n

解決策

\n
エンドポイントのパスを推測しないでください。`GET /endpoints` にあるパスのみが存在します。
    \n
  1. 有効なエンドポイントを確認：curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. URL を正確に比較 — 大文字小文字を区別、末尾スラッシュなし
    3. \n
  3. HTTP メソッドを確認 — GET /memory と POST /memory は異なる
    4. \n
\n

API 呼び出しが 429 を返す

\n

症状

\n\n

解決策

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

Rate Limits を参照。

\n

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

\n

症状

\n\n

解決策

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

FTS5 Search を参照。

\n

メモリが永続化されない

\n

症状

\n\n

解決策

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

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

\n

症状

\n\n

解決策

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

MCP Troubleshooting を参照。

\n

Synapse がオフライン

\n

症状

\n\n

解決策

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

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

\n

データベースエラー

\n

症状

\n\n

解決策

\n

セルフホストの場合：

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

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

\n

Webhook が発火しない

\n

症状

\n\n

解決策

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

Webhooks API を参照。

\n

Cron ジョブが実行されない

\n

症状

\n\n

解決策

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

Cron & Scheduler を参照。

\n

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

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

次のステップ

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}