{"title":"문제 해결 FAQ","slug":"troubleshooting","category":"faq","summary":"일반적인 Synapse 문제에 대한 해결 방법 — 인증, 네트워크, 데이터, 배포.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":613,"read_minutes":3,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 문제 해결 FAQ\n\n일반적인 Synapse 문제에 대한 해결 방법입니다.\n\n## 로그인할 수 없습니다\n\n### 증상\n\n- `POST /login`이 401 반환\n- \"Invalid email or password\"\n\n### 해결 방법\n\n1. **이메일이 올바른지 확인** — 대소문자 구분\n2. **비밀번호 확인** — 최소 6자\n3. 계정이 없는 경우 **먼저 가입**: `POST /register`\n4. (SMTP가 구성된 경우) 웹 UI를 통해 **비밀번호 재설정**\n\n## Mind Key를 분실했습니다\n\n### 증상\n\n- 메모리에 접근할 수 없음\n- Mind Key가 삭제/분실됨\n\n### 해결 방법\n\nMind Key는 복구할 수 없습니다. 다음을 수행해야 합니다:\n\n1. JWT 받기 위해 로그인: `POST /login`\n2. 마인드 나열: `GET /minds` (JWT로)\n3. 새 마인드 생성: `POST /minds`\n4. 새 Mind Key 저장\n5. (선택 사항) 이전 마인드 삭제: `DELETE /minds/:id`\n\nMind Key를 찾을 수 없는 한 **이전 마인드의 데이터는 손실**됩니다.\n\n## API 호출이 401을 반환합니다\n\n### 증상\n\n- 모든 API 호출이 401 Unauthorized 반환\n- \"Mind Key fehlt oder ungültig\"\n\n### 해결 방법\n\n1. **헤더 형식 확인**: `Authorization: Bearer mk_...`\n2. **Mind Key가 `mk_`로 시작하는지 확인** (`eyJ`는 JWT)\n3. **직접 테스트**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key가 취소되었을 수 있음** — 새 마인드 생성\n\n[Authentication](/docs/getting-started/authentication)을 참조하십시오.\n\n## API 호출이 404를 반환합니다\n\n### 증상\n\n- 404 Not Found\n- \"Route not found\"\n\n### 해결 방법\n\n> [!CRITICAL]\n> 엔드포인트 경로를 추측하지 마십시오. `GET /endpoints`의 경로만 존재합니다.\n\n1. **유효한 엔드포인트 확인**: `curl https://synapse.schaefer.zone/endpoints`\n2. **URL을 정확히 비교** — 대소문자 구분, 후행 슬래시 없음\n3. **HTTP 메서드 확인** — `GET /memory`와 `POST /memory`는 다름\n\n## API 호출이 429를 반환합니다\n\n### 증상\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### 해결 방법\n\n1. **헤더 인증으로 전환** (속도 제한 없음):\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. `?key=`를 사용해야 하는 경우 `Retry-After`초 대기\n\n[속도 제한](/docs/api/rate-limits)을 참조하십시오.\n\n## 메모리 검색이 결과를 반환하지 않습니다\n\n### 증상\n\n- `GET /memory/search?q=...`가 빈 결과 반환\n- 메모리가 존재한다는 것을 알고 있음\n\n### 해결 방법\n\n1. **메모리 존재 확인**: `GET /memory/recall`\n2. **검색 구문 확인** — FTS5는 특정 구문이 있음\n3. **더 단순한 쿼리 시도** — `?q=docker+swarm+deployment` 대신 `?q=docker`\n4. 개념적 쿼리에 **의미론적 검색 사용**: `GET /memory/semantic-search?q=...`\n\n[FTS5 검색](/docs/concepts/fts5-search)을 참조하십시오.\n\n## 메모리가 유지되지 않습니다\n\n### 증상\n\n- POST /memory가 성공 반환\n- GET /memory/recall에 표시되지 않음\n\n### 해결 방법\n\n1. **동일한 Mind Key 확인** — 다른 키 = 다른 마인드\n2. **응답 확인** — POST는 `{ \"id\": \"mem_...\", \"status\": \"stored\" }` 반환\n3. /memory/recall (텍스트) 대신 **GET /memory** (JSON 목록) 시도\n4. **필터 확인** — `?category=` 또는 `?tag=`가 숨기고 있을 수 있음\n\n## Claude Desktop에 도구가 나타나지 않습니다\n\n### 증상\n\n- Claude Desktop이 0개 도구 표시\n- 🔌 아이콘 없음\n\n### 해결 방법\n\n1. **Claude Desktop 완전히 재시작** (Cmd+Q)\n2. **구성 파일이 유효한 JSON인지 확인**\n3. **Node.js 18+ 설치 확인**\n4. **MCP 수동 실행**: `npx -y synapse-mcp-api@latest`\n5. **로그 확인**: `~/Library/Logs/Claude/mcp.log`\n\n[MCP 문제 해결](/docs/mcp/troubleshooting)을 참조하십시오.\n\n## Synapse가 오프라인입니다\n\n### 증상\n\n- synapse.schaefer.zone에 도달할 수 없음\n- curl 시간 초과\n\n### 해결 방법\n\n1. **인터넷 확인** — 다른 사이트 시도\n2. **Synapse 상태 확인**: `curl https://synapse.schaefer.zone/health`\n3. **대기** — 일시적 중단 또는 배포일 수 있음\n4. **상태 페이지 확인** (있는 경우)\n\n자체 호스팅의 경우: Docker 컨테이너 상태, 데이터베이스 연결 확인.\n\n## 데이터베이스 오류\n\n### 증상\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### 해결 방법\n\n자체 호스팅의 경우:\n\n1. **PostgreSQL 실행 확인**: `docker ps | grep postgres`\n2. 환경의 **DATABASE_URL 확인**\n3. **마이그레이션 확인**: `npm run migrate:check`\n4. **디스크 공간 확인**: `df -h`\n\n호스팅의 경우: 지원팀에 보고.\n\n## 웹훅이 발생하지 않습니다\n\n### 증상\n\n- 웹훅을 등록했지만 콜백을 받지 못함\n- 귀하의 URL로 POST 없음\n\n### 해결 방법\n\n1. **URL이 접근 가능한지 확인**: `curl -X POST your-url -d '{}'`\n2. **이벤트 필터 확인** — `memory.*`는 모든 메모리 이벤트 매칭\n3. **웹훅 테스트**: `POST /webhooks/:id/test`\n4. **웹훅 활성화 확인**: `GET /webhooks/:id`\n5. **SSL 확인** — Synapse는 웹훅 URL에 유효한 HTTPS 필요\n\n[Webhooks API](/docs/api/webhooks)를 참조하십시오.\n\n## Cron 작업이 실행되지 않습니다\n\n### 증상\n\n- cron 작업을 생성했지만 실행되지 않음\n- `next_run`이 업데이트되지 않음\n\n### 해결 방법\n\n1. **스케줄 구문 확인** — 유효한 5필드 cron 또는 정수 초여야 함\n2. **엔드포인트가 허용되는지 확인** — http(s)여야 하며, 사설 IP 불가\n3. **작업 활성화 확인**: `GET /cron`\n4. **다음 예약 시간까지 대기** — cron은 즉시 실행되지 않음\n\n[Cron 및 Scheduler](/docs/api/cron)를 참조하십시오.\n\n## 추가 도움이 필요하십니까?\n\n1. **기존 문서 확인**: \n2. **문서 검색**: `GET /docs/search?q=your+question`\n3. **이슈 열기**: \n4. **연락**: `/support` 페이지 참조\n\n## 다음 단계\n\n- [오류 및 오류 처리](/docs/api/errors)\n- [API FAQ](/docs/faq/api-faq)\n- [MCP 문제 해결](/docs/mcp/troubleshooting)\n","content_html":"

문제 해결 FAQ

\n

일반적인 Synapse 문제에 대한 해결 방법입니다.

\n

로그인할 수 없습니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. 이메일이 올바른지 확인 — 대소문자 구분
    2. \n
  2. 비밀번호 확인 — 최소 6자
    3. \n
  3. 계정이 없는 경우 먼저 가입: POST /register
    4. \n
  4. (SMTP가 구성된 경우) 웹 UI를 통해 비밀번호 재설정
    5. \n
\n

Mind Key를 분실했습니다

\n

증상

\n\n

해결 방법

\n

Mind Key는 복구할 수 없습니다. 다음을 수행해야 합니다:

\n
    \n
  1. JWT 받기 위해 로그인: POST /login
    2. \n
  2. 마인드 나열: GET /minds (JWT로)
    3. \n
  3. 새 마인드 생성: POST /minds
    4. \n
  4. 새 Mind Key 저장
    5. \n
  5. (선택 사항) 이전 마인드 삭제: DELETE /minds/:id
    6. \n
\n

Mind Key를 찾을 수 없는 한 이전 마인드의 데이터는 손실됩니다.

\n

API 호출이 401을 반환합니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. 헤더 형식 확인: Authorization: Bearer mk_...
    2. \n
  2. Mind Key가 mk_로 시작하는지 확인 (eyJ는 JWT)
    3. \n
  3. 직접 테스트:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key가 취소되었을 수 있음 — 새 마인드 생성
    5. \n
\n

Authentication을 참조하십시오.

\n

API 호출이 404를 반환합니다

\n

증상

\n\n

해결 방법

\n
엔드포인트 경로를 추측하지 마십시오. `GET /endpoints`의 경로만 존재합니다.
    \n
  1. 유효한 엔드포인트 확인: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. URL을 정확히 비교 — 대소문자 구분, 후행 슬래시 없음
    3. \n
  3. HTTP 메서드 확인 — GET /memory와 POST /memory는 다름
    4. \n
\n

API 호출이 429를 반환합니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. 헤더 인증으로 전환 (속도 제한 없음):
    # Don't\ncurl ".../memory/recall?key=mk_..."\n\n# Do\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. ?key=를 사용해야 하는 경우 Retry-After초 대기
    3. \n
\n

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

\n

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

\n

증상

\n\n

해결 방법

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

FTS5 검색을 참조하십시오.

\n

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

\n

증상

\n\n

해결 방법

\n
    \n
  1. 동일한 Mind Key 확인 — 다른 키 = 다른 마인드
    2. \n
  2. 응답 확인 — POST는 { "id": "mem_...", "status": "stored" } 반환
    3. \n
  3. /memory/recall (텍스트) 대신 GET /memory (JSON 목록) 시도
    4. \n
  4. 필터 확인 — ?category= 또는 ?tag=가 숨기고 있을 수 있음
    5. \n
\n

Claude Desktop에 도구가 나타나지 않습니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. Claude Desktop 완전히 재시작 (Cmd+Q)
    2. \n
  2. 구성 파일이 유효한 JSON인지 확인
    3. \n
  3. Node.js 18+ 설치 확인
    4. \n
  4. MCP 수동 실행: npx -y synapse-mcp-api@latest
    5. \n
  5. 로그 확인: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

MCP 문제 해결을 참조하십시오.

\n

Synapse가 오프라인입니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. 인터넷 확인 — 다른 사이트 시도
    2. \n
  2. Synapse 상태 확인: curl https://synapse.schaefer.zone/health
    3. \n
  3. 대기 — 일시적 중단 또는 배포일 수 있음
    4. \n
  4. 상태 페이지 확인 (있는 경우)
    5. \n
\n

자체 호스팅의 경우: Docker 컨테이너 상태, 데이터베이스 연결 확인.

\n

데이터베이스 오류

\n

증상

\n\n

해결 방법

\n

자체 호스팅의 경우:

\n
    \n
  1. PostgreSQL 실행 확인: docker ps | grep postgres
    2. \n
  2. 환경의 DATABASE_URL 확인
    3. \n
  3. 마이그레이션 확인: npm run migrate:check
    4. \n
  4. 디스크 공간 확인: df -h
    5. \n
\n

호스팅의 경우: 지원팀에 보고.

\n

웹훅이 발생하지 않습니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. URL이 접근 가능한지 확인: curl -X POST your-url -d '{}'
    2. \n
  2. 이벤트 필터 확인 — memory.*는 모든 메모리 이벤트 매칭
    3. \n
  3. 웹훅 테스트: POST /webhooks/:id/test
    4. \n
  4. 웹훅 활성화 확인: GET /webhooks/:id
    5. \n
  5. SSL 확인 — Synapse는 웹훅 URL에 유효한 HTTPS 필요
    6. \n
\n

Webhooks API를 참조하십시오.

\n

Cron 작업이 실행되지 않습니다

\n

증상

\n\n

해결 방법

\n
    \n
  1. 스케줄 구문 확인 — 유효한 5필드 cron 또는 정수 초여야 함
    2. \n
  2. 엔드포인트가 허용되는지 확인 — http(s)여야 하며, 사설 IP 불가
    3. \n
  3. 작업 활성화 확인: GET /cron
    4. \n
  4. 다음 예약 시간까지 대기 — cron은 즉시 실행되지 않음
    5. \n
\n

Cron 및 Scheduler를 참조하십시오.

\n

추가 도움이 필요하십니까?

\n
    \n
  1. 기존 문서 확인: https://synapse.schaefer.zone/docs
    2. \n
  2. 문서 검색: GET /docs/search?q=your+question
    3. \n
  3. 이슈 열기: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. 연락: /support 페이지 참조
    5. \n
\n

다음 단계

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