{"title":"FAQ khắc phục sự cố","slug":"troubleshooting","category":"faq","summary":"Giải pháp cho các vấn đề Synapse phổ biến — xác thực, mạng, dữ liệu, triển khai.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":850,"read_minutes":4,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# FAQ khắc phục sự cố\n\nGiải pháp cho các vấn đề Synapse phổ biến.\n\n## Tôi không thể đăng nhập\n\n### Triệu chứng\n\n- `POST /login` trả về 401\n- \"Invalid email or password\"\n\n### Giải pháp\n\n1. **Xác minh email chính xác** — phân biệt chữ hoa chữ thường\n2. **Kiểm tra mật khẩu** — tối thiểu 6 ký tự\n3. **Đăng ký trước** nếu bạn không có tài khoản: `POST /register`\n4. **Đặt lại mật khẩu** (nếu SMTP được cấu hình) qua giao diện web\n\n## Tôi mất Mind Key\n\n### Triệu chứng\n\n- Không thể truy cập bộ nhớ\n- Mind Key đã bị xóa/mất\n\n### Giải pháp\n\nMind Key không thể khôi phục. Bạn phải:\n\n1. Đăng nhập để lấy JWT: `POST /login`\n2. Liệt kê mind: `GET /minds` (với JWT)\n3. Tạo mind mới: `POST /minds`\n4. Lưu Mind Key mới\n5. (Tùy chọn) Xóa mind cũ: `DELETE /minds/:id`\n\n**Dữ liệu trong mind cũ bị mất** trừ khi bạn có thể tìm thấy Mind Key.\n\n## Lệnh gọi API trả về 401\n\n### Triệu chứng\n\n- Tất cả lệnh gọi API trả về 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Giải pháp\n\n1. **Xác minh định dạng header**: `Authorization: Bearer mk_...`\n2. **Kiểm tra Mind Key bắt đầu bằng `mk_`** (không phải `eyJ` là JWT)\n3. **Kiểm tra trực tiếp**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key có thể bị thu hồi** — tạo mind mới\n\nXem [Xác thực](/docs/getting-started/authentication).\n\n## Lệnh gọi API trả về 404\n\n### Triệu chứng\n\n- 404 Not Found\n- \"Route not found\"\n\n### Giải pháp\n\n> [!CRITICAL]\n> Không đoán đường dẫn endpoint. Chỉ đường dẫn trong `GET /endpoints` mới tồn tại.\n\n1. **Kiểm tra endpoint hợp lệ**: `curl https://synapse.schaefer.zone/endpoints`\n2. **So sánh URL chính xác** — phân biệt chữ hoa chữ thường, không có dấu gạch chéo cuối\n3. **Kiểm tra phương thức HTTP** — `GET /memory` khác với `POST /memory`\n\n## Lệnh gọi API trả về 429\n\n### Triệu chứng\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Giải pháp\n\n1. **Chuyển sang xác thực header** (không giới hạn tốc độ):\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Đợi `Retry-After` giây** nếu bạn phải dùng `?key=`\n\nXem [Giới hạn tốc độ](/docs/api/rate-limits).\n\n## Tìm kiếm bộ nhớ không trả về kết quả\n\n### Triệu chứng\n\n- `GET /memory/search?q=...` trả về rỗng\n- Biết bộ nhớ tồn tại\n\n### Giải pháp\n\n1. **Xác minh bộ nhớ tồn tại**: `GET /memory/recall`\n2. **Kiểm tra cú pháp tìm kiếm** — FTS5 có cú pháp cụ thể\n3. **Thử truy vấn đơn giản hơn** — `?q=docker` thay vì `?q=docker+swarm+deployment`\n4. **Sử dụng tìm kiếm ngữ nghĩa** cho truy vấn khái niệm: `GET /memory/semantic-search?q=...`\n\nXem [Tìm kiếm FTS5](/docs/concepts/fts5-search).\n\n## Bộ nhớ không tồn tại\n\n### Triệu chứng\n\n- POST /memory trả về thành công\n- GET /memory/recall không hiển thị chúng\n\n### Giải pháp\n\n1. **Xác minh cùng Mind Key** — key khác = mind khác\n2. **Kiểm tra phản hồi** — POST trả về `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Thử GET /memory** (danh sách JSON) thay vì /memory/recall (văn bản)\n4. **Kiểm tra bộ lọc** — `?category=` hoặc `?tag=` có thể ẩn chúng\n\n## Công cụ không xuất hiện trong Claude Desktop\n\n### Triệu chứng\n\n- Claude Desktop hiển thị 0 công cụ\n- Không có biểu tượng 🔌\n\n### Giải pháp\n\n1. **Khởi động lại Claude Desktop hoàn toàn** (Cmd+Q)\n2. **Xác minh tệp cấu hình** là JSON hợp lệ\n3. **Kiểm tra Node.js 18+** đã cài đặt\n4. **Chạy MCP thủ công**: `npx -y synapse-mcp-api@latest`\n5. **Kiểm tra nhật ký**: `~/Library/Logs/Claude/mcp.log`\n\nXem [Khắc phục sự cố MCP](/docs/mcp/troubleshooting).\n\n## Synapse ngoại tuyến\n\n### Triệu chứng\n\n- Không thể truy cập synapse.schaefer.zone\n- curl hết thời gian chờ\n\n### Giải pháp\n\n1. **Kiểm tra internet của bạn** — thử một trang khác\n2. **Kiểm tra sức khỏe Synapse**: `curl https://synapse.schaefer.zone/health`\n3. **Đợi** — có thể là sự cố tạm thời hoặc triển khai\n4. **Kiểm tra trang trạng thái** (nếu có)\n\nCho tự lưu trữ: kiểm tra trạng thái Docker container, kết nối database.\n\n## Lỗi database\n\n### Triệu chứng\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Giải pháp\n\nCho tự lưu trữ:\n\n1. **Kiểm tra PostgreSQL đang chạy**: `docker ps | grep postgres`\n2. **Kiểm tra DATABASE_URL** trong env\n3. **Kiểm tra migration**: `npm run migrate:check`\n4. **Kiểm tra không gian đĩa**: `df -h`\n\nCho phiên bản được lưu trữ: báo cáo cho hỗ trợ.\n\n## Webhook không kích hoạt\n\n### Triệu chứng\n\n- Đã đăng ký webhook nhưng không nhận callback\n- Không có POST đến URL của bạn\n\n### Giải pháp\n\n1. **Xác minh URL có thể truy cập**: `curl -X POST your-url -d '{}'`\n2. **Kiểm tra bộ lọc sự kiện** — `memory.*` khớp tất cả sự kiện memory\n3. **Kiểm tra webhook**: `POST /webhooks/:id/test`\n4. **Kiểm tra webhook được bật**: `GET /webhooks/:id`\n5. **Xác minh SSL** — Synapse yêu cầu HTTPS hợp lệ cho URL webhook\n\nXem [Webhooks API](/docs/api/webhooks).\n\n## Cron job không chạy\n\n### Triệu chứng\n\n- Đã tạo cron job nhưng không kích hoạt\n- `next_run` không cập nhật\n\n### Giải pháp\n\n1. **Kiểm tra cú pháp lịch** — phải là cron 5 trường HOẶC số nguyên giây hợp lệ\n2. **Xác minh endpoint được phép** — phải là http(s), không IP riêng\n3. **Kiểm tra job được bật**: `GET /cron`\n4. **Đợi thời gian lên lịch tiếp theo** — cron không tức thời\n\nXem [Cron & Scheduler](/docs/api/cron).\n\n## Cần thêm trợ giúp?\n\n1. **Kiểm tra tài liệu hiện có**: \n2. **Tìm kiếm tài liệu**: `GET /docs/search?q=your+question`\n3. **Mở issue**: \n4. **Liên hệ**: xem trang `/support`\n\n## Bước tiếp theo\n\n- [Lỗi & Xử lý lỗi](/docs/api/errors)\n- [FAQ API](/docs/faq/api-faq)\n- [Khắc phục sự cố MCP](/docs/mcp/troubleshooting)\n","content_html":"

FAQ khắc phục sự cố

\n

Giải pháp cho các vấn đề Synapse phổ biến.

\n

Tôi không thể đăng nhập

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Xác minh email chính xác — phân biệt chữ hoa chữ thường
    2. \n
  2. Kiểm tra mật khẩu — tối thiểu 6 ký tự
    3. \n
  3. Đăng ký trước nếu bạn không có tài khoản: POST /register
    4. \n
  4. Đặt lại mật khẩu (nếu SMTP được cấu hình) qua giao diện web
    5. \n
\n

Tôi mất Mind Key

\n

Triệu chứng

\n\n

Giải pháp

\n

Mind Key không thể khôi phục. Bạn phải:

\n
    \n
  1. Đăng nhập để lấy JWT: POST /login
    2. \n
  2. Liệt kê mind: GET /minds (với JWT)
    3. \n
  3. Tạo mind mới: POST /minds
    4. \n
  4. Lưu Mind Key mới
    5. \n
  5. (Tùy chọn) Xóa mind cũ: DELETE /minds/:id
    6. \n
\n

Dữ liệu trong mind cũ bị mất trừ khi bạn có thể tìm thấy Mind Key.

\n

Lệnh gọi API trả về 401

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Xác minh định dạng header: Authorization: Bearer mk_...
    2. \n
  2. Kiểm tra Mind Key bắt đầu bằng mk_ (không phải eyJ là JWT)
    3. \n
  3. Kiểm tra trực tiếp:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key có thể bị thu hồi — tạo mind mới
    5. \n
\n

Xem Xác thực.

\n

Lệnh gọi API trả về 404

\n

Triệu chứng

\n\n

Giải pháp

\n
Không đoán đường dẫn endpoint. Chỉ đường dẫn trong `GET /endpoints` mới tồn tại.
    \n
  1. Kiểm tra endpoint hợp lệ: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. So sánh URL chính xác — phân biệt chữ hoa chữ thường, không có dấu gạch chéo cuối
    3. \n
  3. Kiểm tra phương thức HTTP — GET /memory khác với POST /memory
    4. \n
\n

Lệnh gọi API trả về 429

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Chuyển sang xác thực header (không giới hạn tốc độ):
    # Don't\ncurl ".../memory/recall?key=mk_..."\n\n# Do\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Đợi Retry-After giây nếu bạn phải dùng ?key=
    3. \n
\n

Xem Giới hạn tốc độ.

\n

Tìm kiếm bộ nhớ không trả về kết quả

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Xác minh bộ nhớ tồn tại: GET /memory/recall
    2. \n
  2. Kiểm tra cú pháp tìm kiếm — FTS5 có cú pháp cụ thể
    3. \n
  3. Thử truy vấn đơn giản hơn — ?q=docker thay vì ?q=docker+swarm+deployment
    4. \n
  4. Sử dụng tìm kiếm ngữ nghĩa cho truy vấn khái niệm: GET /memory/semantic-search?q=...
    5. \n
\n

Xem Tìm kiếm FTS5.

\n

Bộ nhớ không tồn tại

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Xác minh cùng Mind Key — key khác = mind khác
    2. \n
  2. Kiểm tra phản hồi — POST trả về { "id": "mem_...", "status": "stored" }
    3. \n
  3. Thử GET /memory (danh sách JSON) thay vì /memory/recall (văn bản)
    4. \n
  4. Kiểm tra bộ lọc — ?category= hoặc ?tag= có thể ẩn chúng
    5. \n
\n

Công cụ không xuất hiện trong Claude Desktop

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Khởi động lại Claude Desktop hoàn toàn (Cmd+Q)
    2. \n
  2. Xác minh tệp cấu hình là JSON hợp lệ
    3. \n
  3. Kiểm tra Node.js 18+ đã cài đặt
    4. \n
  4. Chạy MCP thủ công: npx -y synapse-mcp-api@latest
    5. \n
  5. Kiểm tra nhật ký: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

Xem Khắc phục sự cố MCP.

\n

Synapse ngoại tuyến

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Kiểm tra internet của bạn — thử một trang khác
    2. \n
  2. Kiểm tra sức khỏe Synapse: curl https://synapse.schaefer.zone/health
    3. \n
  3. Đợi — có thể là sự cố tạm thời hoặc triển khai
    4. \n
  4. Kiểm tra trang trạng thái (nếu có)
    5. \n
\n

Cho tự lưu trữ: kiểm tra trạng thái Docker container, kết nối database.

\n

Lỗi database

\n

Triệu chứng

\n\n

Giải pháp

\n

Cho tự lưu trữ:

\n
    \n
  1. Kiểm tra PostgreSQL đang chạy: docker ps | grep postgres
    2. \n
  2. Kiểm tra DATABASE_URL trong env
    3. \n
  3. Kiểm tra migration: npm run migrate:check
    4. \n
  4. Kiểm tra không gian đĩa: df -h
    5. \n
\n

Cho phiên bản được lưu trữ: báo cáo cho hỗ trợ.

\n

Webhook không kích hoạt

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Xác minh URL có thể truy cập: curl -X POST your-url -d '{}'
    2. \n
  2. Kiểm tra bộ lọc sự kiện — memory.* khớp tất cả sự kiện memory
    3. \n
  3. Kiểm tra webhook: POST /webhooks/:id/test
    4. \n
  4. Kiểm tra webhook được bật: GET /webhooks/:id
    5. \n
  5. Xác minh SSL — Synapse yêu cầu HTTPS hợp lệ cho URL webhook
    6. \n
\n

Xem Webhooks API.

\n

Cron job không chạy

\n

Triệu chứng

\n\n

Giải pháp

\n
    \n
  1. Kiểm tra cú pháp lịch — phải là cron 5 trường HOẶC số nguyên giây hợp lệ
    2. \n
  2. Xác minh endpoint được phép — phải là http(s), không IP riêng
    3. \n
  3. Kiểm tra job được bật: GET /cron
    4. \n
  4. Đợi thời gian lên lịch tiếp theo — cron không tức thời
    5. \n
\n

Xem Cron & Scheduler.

\n

Cần thêm trợ giúp?

\n
    \n
  1. Kiểm tra tài liệu hiện có: https://synapse.schaefer.zone/docs
    2. \n
  2. Tìm kiếm tài liệu: GET /docs/search?q=your+question
    3. \n
  3. Mở issue: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Liên hệ: xem trang /support
    5. \n
\n

Bước tiếp theo

\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"]}