문제 해결

증상별 원인과 조치입니다.

설치·설정

증상	원인	조치
저장소 뿌리를 찾지 못했다	NOTIONML_STORE가 없거나 디렉터리가 아님	경로를 확인하고 export NOTIONML_STORE=…
nl: command not found	설치 경로가 PATH에 없음	uv tool dir --bin을 PATH에 추가하거나 notion-ml 사용
nl이 다른 프로그램을 실행함	셸 내장 명령과 이름 충돌	notion-ml을 사용

인증

증상	원인	조치
401 Unauthorized	토큰 없음·만료	토큰 파일 권한과 값을 확인하고 nl auth status notion
404 Could not find block	통합이 페이지에 초대되지 않음	페이지 ⋯ → 연결 → 통합 추가
body failed validation	요청 형식이 API 버전과 불일치	nl --version 확인 후 최신 도구로 갱신

비교·반영

증상	원인	조치
진행할 수 없다 — type_mismatch	같은 자리의 블록 종류가 다름	nl pull로 원격을 채택하거나, 로컬을 그 종류로 맞춤
<원격 우선>이 계속 나옴	사람이 노션에서 마지막으로 고침	nl pull <노트>#n 또는 nl keep <노트>#n
diff가 바뀌었다	add 이후 소스가 수정됨	nl diff로 다시 확인하고 nl add 재실행
다른 실행이 쓰는 중이다	다른 프로세스가 잠금 보유	끝난 뒤 다시 실행. 남아 있으면 records/.lock 확인
검증 실패	쓴 결과가 계획과 다름	출력된 스냅숏으로 되돌리고 원인 확인
거부(댓글 앵커)	그 블록·행에 댓글이 있음	노션에서 직접 수정하거나 댓글을 옮긴 뒤 재시도

표·그림

증상	원인	조치
table_width_changed	로컬 표의 열 수가 다름	노션 표를 같은 열 수로 맞추거나 표를 재작성
E-TYP-03 표의 칸 수가 머리행과 다르다	행마다 칸 수 불일치	빠진 칸을 채움
그림이 반영되지 않음	파일 업로드 미구현	원격 URL 그림을 쓰거나 업로드를 기다림

진단

python -m notionml.core lint <노트>   # 노트 자체 검사
nl config                             # 경로·설정 출처
nl auth status                        # 토큰 상태

저널과 스냅숏은 store/records/에 있습니다. apply-journal/*.json의 state가 verify_failed면 그 파일과 같은 시각의 스냅숏을 확인하십시오.