# 문제 해결 FAQ
SUMMARY: 일반적인 Synapse 문제에 대한 해결 방법 — 인증, 네트워크, 데이터, 배포.

문제 해결 FAQ
일반적인 Synapse 문제에 대한 해결 방법입니다.
로그인할 수 없습니다
증상
- 이 401 반환
- "Invalid email or password"
해결 방법
1. 이메일이 올바른지 확인 — 대소문자 구분
2. 비밀번호 확인 — 최소 6자
3. 계정이 없는 경우 먼저 가입: 
4. (SMTP가 구성된 경우) 웹 UI를 통해 비밀번호 재설정
Mind Key를 분실했습니다
증상
- 메모리에 접근할 수 없음
- Mind Key가 삭제/분실됨
해결 방법
Mind Key는 복구할 수 없습니다. 다음을 수행해야 합니다:
1. JWT 받기 위해 로그인: 
2. 마인드 나열:  (JWT로)
3. 새 마인드 생성: 
4. 새 Mind Key 저장
5. (선택 사항) 이전 마인드 삭제: 
Mind Key를 찾을 수 없는 한 이전 마인드의 데이터는 손실됩니다.
API 호출이 401을 반환합니다
증상
- 모든 API 호출이 401 Unauthorized 반환
- "Mind Key fehlt oder ungültig"
해결 방법
1. 헤더 형식 확인: 
2. Mind Key가 로 시작하는지 확인 (는 JWT)
3. 직접 테스트:
   [CODE BLOCK]
4. Mind Key가 취소되었을 수 있음 — 새 마인드 생성
Authentication을 참조하십시오.
API 호출이 404를 반환합니다
증상
- 404 Not Found
- "Route not found"
해결 방법
> [!CRITICAL]
> 엔드포인트 경로를 추측하지 마십시오. 의 경로만 존재합니다.
1. 유효한 엔드포인트 확인: 
2. URL을 정확히 비교 — 대소문자 구분, 후행 슬래시 없음
3. HTTP 메서드 확인 — 와 는 다름
API 호출이 429를 반환합니다
증상
- 429 Too Many Requests
- "Rate limit exceeded"
해결 방법
1. 헤더 인증으로 전환 (속도 제한 없음):
   [CODE BLOCK]
2. 를 사용해야 하는 경우 초 대기
속도 제한을 참조하십시오.
메모리 검색이 결과를 반환하지 않습니다
증상
- 가 빈 결과 반환
- 메모리가 존재한다는 것을 알고 있음
해결 방법
1. 메모리 존재 확인: 
2. 검색 구문 확인 — FTS5는 특정 구문이 있음
3. 더 단순한 쿼리 시도 —  대신 
4. 개념적 쿼리에 의미론적 검색 사용: 
FTS5 검색을 참조하십시오.
메모리가 유지되지 않습니다
증상
- POST /memory가 성공 반환
- GET /memory/recall에 표시되지 않음
해결 방법
1. 동일한 Mind Key 확인 — 다른 키 = 다른 마인드
2. 응답 확인 — POST는  반환
3. /memory/recall (텍스트) 대신 GET /memory (JSON 목록) 시도
4. 필터 확인 —  또는 가 숨기고 있을 수 있음
Claude Desktop에 도구가 나타나지 않습니다
증상
- Claude Desktop이 0개 도구 표시
- 🔌 아이콘 없음
해결 방법
1. Claude Desktop 완전히 재시작 (Cmd+Q)
2. 구성 파일이 유효한 JSON인지 확인
3. Node.js 18+ 설치 확인
4. MCP 수동 실행: 
5. 로그 확인: 
MCP 문제 해결을 참조하십시오.
Synapse가 오프라인입니다
증상
- synapse.schaefer.zone에 도달할 수 없음
- curl 시간 초과
해결 방법
1. 인터넷 확인 — 다른 사이트 시도
2. Synapse 상태 확인: 
3. 대기 — 일시적 중단 또는 배포일 수 있음
4. 상태 페이지 확인 (있는 경우)
자체 호스팅의 경우: Docker 컨테이너 상태, 데이터베이스 연결 확인.
데이터베이스 오류
증상
- 500 Internal Server Error
- "Database connection failed"
해결 방법
자체 호스팅의 경우:
1. PostgreSQL 실행 확인: 
2. 환경의 DATABASEURL 확인
3. 마이그레이션 확인: 
4. 디스크 공간 확인: 
호스팅의 경우: 지원팀에 보고.
웹훅이 발생하지 않습니다
증상
- 웹훅을 등록했지만 콜백을 받지 못함
- 귀하의 URL로 POST 없음
해결 방법
1. URL이 접근 가능한지 확인: 
2. 이벤트 필터 확인 — 는 모든 메모리 이벤트 매칭
3. 웹훅 테스트: 
4. 웹훅 활성화 확인: 
5. SSL 확인 — Synapse는 웹훅 URL에 유효한 HTTPS 필요
Webhooks API를 참조하십시오.
Cron 작업이 실행되지 않습니다
증상
- cron 작업을 생성했지만 실행되지 않음
- 이 업데이트되지 않음
해결 방법
1. 스케줄 구문 확인 — 유효한 5필드 cron 또는 정수 초여야 함
2. 엔드포인트가 허용되는지 확인 — http(s)여야 하며, 사설 IP 불가
3. 작업 활성화 확인: 
4. 다음 예약 시간까지 대기 — cron은 즉시 실행되지 않음
Cron 및 Scheduler를 참조하십시오.
추가 도움이 필요하십니까?
1. 기존 문서 확인: <https://synapse.schaefer.zone/docs>
2. 문서 검색: 
3. 이슈 열기: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. 연락:  페이지 참조
다음 단계
- 오류 및 오류 처리
- API FAQ
- MCP 문제 해결