Troubleshooting

MCP 연결

도구 목록에 ainote 가 안 나옴

증상: Claude Code /mcp 에 ainote 보이지 않음.

원인 + 해결:

1. type 필드 누락 (가장 흔함)

   { "type": "http", "url": "..." }

   type 빠지면 mcpServers 블록 전체가 schema 검증 실패 → 다른 MCP 도 같이 안 뜸.

2. JSON 문법 오류 — ~/.claude.json 을 jq . 로 검증

   jq . ~/.claude.json > /dev/null

3. Claude Code 재시작 필요 — 설정 변경 후 reload 필수.

401 Unauthorized

{ "error": { "code": -32001, "message": "Unauthorized" } }

원인:

• Authorization 헤더 누락
• 키 prefix 잘못 (McpKey 접두사 + 공백 1개)
• 키 만료/폐기됨

테스트:

curl -X POST https://api.ainote.dev/api/mcp \
  -H "Authorization: McpKey YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

응답 끊김 / Cold Start

Render free tier 는 15분 idle 시 sleep. 첫 호출 ~5초 wait.

해결: 유료 플랜 또는 cron 으로 1분마다 ping.

태스크

자연어 파싱이 이상해요

"내일 오후 3시" 가 다음날 오후 3시로 안 잡힐 때:

• 시간대 확인 — Asia/Seoul 기본, 사용자 설정에서 변경 가능
• 명시적으로 ISO 8601 사용: 2026-05-08T15:00:00+09:00

알림이 안 와요

체크리스트:

1. iOS/Android 앱 알림 권한 ON
2. Telegram 봇 연동 완료 (설정 → Telegram)
3. Web Push: 브라우저에서 ainote.dev 알림 허용
4. reminder_minutes 설정됨? (기본 알림 없음)
5. Solid Queue 정상 동작 — bin/jobs status (셀프호스팅)

메모리 / Dev Docs

pull_dev_docs 가 파일 만들지 않음

원인: 등록할 때 local_path 안 넣었음.

확인:

ainote 에서 "tennis-bracket-claude.md" 의 local_path 보여줘

빈값이면:

local_path 를 "/Users/seunghan/tennis_bracket/CLAUDE.md" 로 업데이트해줘

CLAUDE.md 동기화 충돌

두 기기에서 동시 편집 → 마지막 write 가 이김 (LWW).

복구:

# 양쪽 버전 확인
git log -p --all -- "global/claude/global-claude-guidelines.md"

# 손실된 버전 복원
git show <SHA>:global/claude/global-claude-guidelines.md > /tmp/lost.md

Vault

vault_sync 가 conflict 표시

Git 3-way merge conflict. 수동 해결:

cd ~/ainote-vaults/<vault-name>
git status                    # conflict 파일 확인
# editor 로 conflict marker 해결
git add .
git commit
ainote vault_sync             # 다시 시도

Obsidian 에서 안 보임

체크:

• .obsidian/ 폴더 vault root 에 있나?
• Obsidian 에서 File → Open Vault as Folder 로 열기
• ainote vault 의 git working tree 가 Obsidian vault root

동기화 (Sync)

새 기기에서 state.json 없음

ainote sync_pull --initial

--initial 플래그가 첫 동기화 모드 — manifest 의 모든 sync 항목을 받아옴.

충돌 디렉토리에 파일 쌓임

~/.claude/ainote-sync/conflicts/ 에 파일들:

# 최근 conflict
ls -lt ~/.claude/ainote-sync/conflicts/ | head

# 수동 해결: diff 보고 한쪽 선택
diff conflicts/path__local.md conflicts/path__remote.md

자세히: sync 충돌 해결.

빌드 / 개발

npm run dev 가 안 됨

cd ~/ainote/docs-site
rm -rf node_modules .vitepress/cache
npm install
npm run dev

Node 20+ 필요.

llms.txt 빌드 실패

node scripts/build-llms.mjs

직접 실행해서 오류 확인. public/ 폴더 권한 문제일 수 있음.

더 안 풀리면

• GitHub Issues: https://github.com/seunghan91/ainote/issues
• Email: support@ainote.dev
• 디버그 정보 첨부: 클라이언트 (Claude Code 버전), ~/.claude.json (키 마스킹), 에러 응답 전체