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