문제 해결 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. 직접 테스트:

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

4. Mind Key가 취소되었을 수 있음 — 새 마인드 생성

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초 대기

속도 제한을 참조하십시오.

메모리 검색이 결과를 반환하지 않습니다

증상

• GET /memory/search?q=...가 빈 결과 반환
• 메모리가 존재한다는 것을 알고 있음

해결 방법

1. 메모리 존재 확인: GET /memory/recall
2. 검색 구문 확인 — FTS5는 특정 구문이 있음
3. 더 단순한 쿼리 시도 — ?q=docker+swarm+deployment 대신 ?q=docker
4. 개념적 쿼리에 의미론적 검색 사용: GET /memory/semantic-search?q=...

FTS5 검색을 참조하십시오.

메모리가 유지되지 않습니다

증상

• 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 문제 해결을 참조하십시오.

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를 참조하십시오.

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. 이슈 열기: https://gitlab.com/schaefer-services/synapse/-/issues
4. 연락: /support 페이지 참조

다음 단계

• 오류 및 오류 처리
• API FAQ
• MCP 문제 해결