# 문제 해결 FAQ 일반적인 Synapse 문제에 대한 해결 방법입니다. ## 로그인할 수 없습니다 ### 증상 - `POST /login`이 401 반환 - "Invalid email or password" ### 해결 방법 1. **이메일이 올바른지 확인** — 대소문자 구분 2. **비밀번호 확인** — 최소 6자 3. 계정이 없는 경우 **먼저 가입**: `POST /register` 4. (SMTP가 구성된 경우) 웹 UI를 통해 **비밀번호 재설정** ## Mind Key를 분실했습니다 ### 증상 - 메모리에 접근할 수 없음 - Mind Key가 삭제/분실됨 ### 해결 방법 Mind Key는 복구할 수 없습니다. 다음을 수행해야 합니다: 1. JWT 받기 위해 로그인: `POST /login` 2. 마인드 나열: `GET /minds` (JWT로) 3. 새 마인드 생성: `POST /minds` 4. 새 Mind Key 저장 5. (선택 사항) 이전 마인드 삭제: `DELETE /minds/:id` Mind Key를 찾을 수 없는 한 **이전 마인드의 데이터는 손실**됩니다. ## API 호출이 401을 반환합니다 ### 증상 - 모든 API 호출이 401 Unauthorized 반환 - "Mind Key fehlt oder ungültig" ### 해결 방법 1. **헤더 형식 확인**: `Authorization: Bearer mk_...` 2. **Mind Key가 `mk_`로 시작하는지 확인** (`eyJ`는 JWT) 3. **직접 테스트**: ```bash curl -H "Authorization: Bearer mk_YOUR_KEY" \ https://synapse.schaefer.zone/memory/recall ``` 4. **Mind Key가 취소되었을 수 있음** — 새 마인드 생성 [Authentication](/docs/getting-started/authentication)을 참조하십시오. ## API 호출이 404를 반환합니다 ### 증상 - 404 Not Found - "Route not found" ### 해결 방법 > [!CRITICAL] > 엔드포인트 경로를 추측하지 마십시오. `GET /endpoints`의 경로만 존재합니다. 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. **헤더 인증으로 전환** (속도 제한 없음): ```bash # Don't curl ".../memory/recall?key=mk_..." # Do curl -H "Authorization: Bearer mk_..." .../memory/recall ``` 2. `?key=`를 사용해야 하는 경우 `Retry-After`초 대기 [속도 제한](/docs/api/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 검색](/docs/concepts/fts5-search)을 참조하십시오. ## 메모리가 유지되지 않습니다 ### 증상 - POST /memory가 성공 반환 - GET /memory/recall에 표시되지 않음 ### 해결 방법 1. **동일한 Mind Key 확인** — 다른 키 = 다른 마인드 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 문제 해결](/docs/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` 호스팅의 경우: 지원팀에 보고. ## 웹훅이 발생하지 않습니다 ### 증상 - 웹훅을 등록했지만 콜백을 받지 못함 - 귀하의 URL로 POST 없음 ### 해결 방법 1. **URL이 접근 가능한지 확인**: `curl -X POST your-url -d '{}'` 2. **이벤트 필터 확인** — `memory.*`는 모든 메모리 이벤트 매칭 3. **웹훅 테스트**: `POST /webhooks/:id/test` 4. **웹훅 활성화 확인**: `GET /webhooks/:id` 5. **SSL 확인** — Synapse는 웹훅 URL에 유효한 HTTPS 필요 [Webhooks API](/docs/api/webhooks)를 참조하십시오. ## Cron 작업이 실행되지 않습니다 ### 증상 - cron 작업을 생성했지만 실행되지 않음 - `next_run`이 업데이트되지 않음 ### 해결 방법 1. **스케줄 구문 확인** — 유효한 5필드 cron 또는 정수 초여야 함 2. **엔드포인트가 허용되는지 확인** — http(s)여야 하며, 사설 IP 불가 3. **작업 활성화 확인**: `GET /cron` 4. **다음 예약 시간까지 대기** — cron은 즉시 실행되지 않음 [Cron 및 Scheduler](/docs/api/cron)를 참조하십시오. ## 추가 도움이 필요하십니까? 1. **기존 문서 확인**: 2. **문서 검색**: `GET /docs/search?q=your+question` 3. **이슈 열기**: 4. **연락**: `/support` 페이지 참조 ## 다음 단계 - [오류 및 오류 처리](/docs/api/errors) - [API FAQ](/docs/faq/api-faq) - [MCP 문제 해결](/docs/mcp/troubleshooting)