Node.js 버전으로 인한 키 쌍 조회 실패 디버깅 회고

최근 Fedify 라이브러리를 사용해 ActivityPub 기반 마이크로 블로그를 만드는 튜토리얼을 따라하다가, 예상치 못한 버그에 부딪혔어요. federation.ts 파일에서 키 쌍이 제대로 생성되는데도 조회가 실패하는 문제였죠. 이 글은 그 디버깅 과정을 회고하며, 비슷한 함정을 피할 수 있도록 내용을 정리해봅니다. (튜토리얼 링크: Fedify 튜토리얼 - 테스트 2)

문제: 키 쌍이 DB에 있는데 왜 조회가 안 될까?

프로젝트를 진행하던 중, 사용자(johndoe) 조회(lookup) 요청에서 publicKey 필드가 비어 나오는 이슈가 발생했습니다. 결과는 이랬어요:

Person {
  id: URL "http://localhost:8000/users/johndoe",
  name: "johndoe",
  url: URL "http://localhost:8000/users/johndoe",
  preferredUsername: "johndoe",
  inbox: URL "http://localhost:8000/users/johndoe/inbox",
  endpoints: Endpoints { sharedInbox: URL "http://localhost:8000/inbox" }
}

SQLite DB의 keys 테이블에는 RSASSA-PKCS1-v1_5와 Ed25519 키 쌍이 잘 저장되어 있었는데, ctx.getActorKeyPairs(identifier)가 빈 배열을 반환하니 publicKey가 누락됐어요. 처음엔 DB 쿼리나 키 생성 로직이 잘못된 줄 알았습니다. (유저명: johndoe, 로컬 서버: http://localhost:8000)

디버깅 과정: 30분의 추적

fedify 프로젝트 메인테이너이신 hongminhee님과 채팅하며 실시간으로 디버깅했어요. 타임라인은 다음과 같아요:

• 오전 12:38: 이슈 보고. setKeyPairsDispatcher 구현 공유 (DB 조회 → 키 생성 → pairs 반환).

• 오전 12:42: 로그 추가 조언. return pairs 전에 console.debug({pairs}) 찍어보니 pairs가 제대로 나옴:

•     pairs [
        { privateKey: CryptoKey {...}, publicKey: CryptoKey {...} },  // RSASSA-PKCS1-v1_5
        { privateKey: CryptoKey {...}, publicKey: CryptoKey {...} }   // Ed25519
      ]
  

• 하지만 요청은 실패. 에러: TypeError: t.buffer.transfer is not a function.

• 오전 12:47: DB 초기화 후 재시도. 로그는 찍히지만 실패. 스택 트레이스 확인

•     TypeError: t.buffer.transfer is not a function
      at y (file:///.../chunk-JF3YMNGM.js:1:140)
      // ... (byte-encodings와 Fedify 내부 함수 관련)
  

• 오전 12:59: Node.js 버전 확인. 내 버전: 20.19.2.

• 오전 1:01: Fedify가 Node 22+를 요구한다는 사실 발견. 업그레이드 시도 (nvm use 22.17.0).

• 오전 1:04~1:07: 초기 업그레이드 실패 (터미널 세션 문제). node -v로 확인 후 재시도.

• 오전 1:12: 성공! 조회 정상 작동.

근본 원인: 버전 호환성과 가이드 불일치

• 주요 원인: Node.js 20.19.2에서 ArrayBuffer.prototype.transfer 메서드가 없어 Fedify의 exportSpki 함수가 런타임 에러를 일으킴. Fedify는 Node 22+를 요구하지만, 내 환경은 20이었다.

• 기여 요인:

  • 튜토리얼 가이드가 "Node.js 20 버전 이상"으로 20.19.2로 설치되있던 npm버전을 그대로 사용함. 하지만 실제 Fedify 요구사항은 22+라 불일치.

  • nvm으로 버전 변경 시 터미널 세션 간 동기화 미스 (변경 후 node -v 확인 안 함).

  • 에러가 키 내보내기 단계에서 발생해 초기 증상이 DB 문제로 오해.

해결: 업그레이드와 재테스트

• Node.js를 22.17.0으로 업그레이드 (nvm install/use 후 터미널 재시작).

• npm install 재실행.

• DB 초기화 후 조회 재시도 → 성공.

교훈: 환경 체크부터, 가이드 blind follow 피하기

• 가장 근본 원인: node 버전을 의심하지도 못하고 stack trace 메세지를 제대로 읽지 않아 도움을 요청했던 것

• 버전 관리: 라이브러리 문서의 최소 요구 버전을 공식 사이트에서 확인. 튜토리얼 가이드만 믿지 말고, GitHub README나 package.json의 engines 필드를 살펴보기.

• 디버깅 팁: 로그부터 찍고, 스택 트레이스 키워드로 검색 (e.g., "ArrayBuffer transfer Node.js"). nvm 사용 시 항상 node -v 검증.

• 예방: 프로젝트 시작 전에 체크리스트 (Node 버전, deps 설치). .nvmrc 파일 추가로 자동화.