안녕하세요, 천상나타입니다.

    제가 관리하는 오픈소스 라이브러리를 npm에 올리다가 하루에 세 번을 연달아 막힌 일이 있었어요. 로그인이 안 됐고, 로그인하고 나니 2FA가 막았고, 겨우 통과했더니 publish는 성공이라는데 버전이 안 올라오는 상황이 벌어졌습니다. 재시도하니 더 이상한 에러가 떴고요. 오늘은 그 연쇄 삽질을 정리해봅니다 — 같은 에러 문구로 검색해서 들어오신 분들께 바로 답이 됐으면 합니다.

    오늘 겪은 전체 사건 흐름 — 인증부터 staged 함정까지

    첫 번째 벽 — ENEEDAUTH

    당연한 얘기지만 일단 시작이에요. npm publish를 쳤더니 이렇게 나옵니다.

    
    npm ERR! code ENEEDAUTH
    npm ERR! need auth This command requires you to be logged in.
    

    npm login으로 브라우저 인증을 마치면 됩니다. 여기까지는 누구나 아는 부분이죠. 문제는 다음이었어요.

    두 번째 벽 — 로그인해도 E403

    로그인을 끝내고 다시 publish를 돌렸더니 이번엔 403이 떴습니다. 로그인을 분명히 했는데 말이죠.

    로그인 후에도 publish가 막히는 E403 — bypass 2fa 토큰을 요구

    에러 문구를 자세히 보면 힌트가 있습니다.

    > "Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages."

    제 계정에 2FA(인증 앱)가 켜져 있었는데, npm은 그 상태에서 publish 같은 중요 작업에는 로그인 세션만으론 부족하다고 보는 거였어요. 2FA를 우회할 수 있는 별도 토큰을 요구합니다.

    참고로 요즘 npm은 "2FA를 우회하는 토큰" 자체를 점점 제한하는 방향으로 가고 있어서, 이 메시지를 만나는 사람이 더 늘어날 것 같습니다.

    Granular Access Token 만들기

    해결책은 에러 문구 그대로예요. npmjs.com에서 Granular Access Token을 만들면 됩니다.

    Granular Access Token 설정 — bypass 2fa 체크가 핵심

    프로필 → Access Tokens → Generate New Token → Granular Access Token으로 들어가서 체크할 건 세 가지예요.

    1. Bypass two-factor authentication for publishing — 이거 안 체크하면 토큰을 만들어도 같은 E403이 또 뜹니다. 이 글의 핵심 체크박스예요.
    2. Packages and scopes — 배포할 스코프(제 경우 @moda-grid)를 고르고 Read and write 권한.
    3. Expiration — 만료 기간. 로컬에서만 쓸 거면 짧게 잡아도 됩니다.

    만들면 npm_로 시작하는 토큰이 나오고, 이걸 ~/.npmrc에 넣으면 끝입니다.

    
    npm config set //registry.npmjs.org/:_authToken=<토큰>
    

    이후 publish는 2FA 코드 입력 없이 바로 됩니다. CI에서 쓰는 것과 같은 원리죠.

    세 번째 벽 — 성공인 줄 알았는데 버전이 없다

    토큰을 넣고 다시 돌렸더니 드디어 publish가 통과했습니다. Publishing to registry.npmjs.org가 찍히고 종료 코드도 0이었어요. 이제 됐구나 하고 확인했는데—

    publish는 통과했는데 npm view는 구버전, 재시도하면 E409 staged

    npm view는 계속 이전 버전(2.2.4)을 가리켰습니다. 분명 방금 2.2.5를 올렸는데요.

    당황해서 같은 명령을 다시 쳤더니 이번엔 또 다른 에러가 나왔습니다.

    
    npm error code E409
    npm error 409 Conflict - Cannot publish over previously staged version "2.2.5".
    

    여기서 문구가 힌트예요. "already published"(이미 배포됨)가 아니라 "previously staged" — 업로드는 됐는데 최종 커밋이 안 된 상태라는 뜻입니다. npm의 퍼블리시가 요즘은 두 단계로 돌아가요. 업로드해서 staged 상태로 만들고, 레지스트리가 검증을 거쳐 실제 버전으로 커밋하는 구조입니다. 제 2.2.5는 그 사이에 끼어 있었던 거죠.

    찾아보니 npm/cli#9889에 "publish가 성공이라고 출력됐는데 버전이 안 보이고, 재시도하면 E409 staged가 뜬다"는 같은 증상이 버그 리포트로 올라와 있었습니다. 사람들은 이걸 phantom staged라고 부르더라고요.

    결론 — 그냥 기다리면 됐다

    찾아본 뒤에는 복잡한 대응이 아니었습니다. 약 10분 뒤에 다시 npm view를 쳐보니 2.2.5가 떠 있었어요. staged가 뒤늦게 커밋된 겁니다.

    만약 같은 상황이면 순서는 이렇습니다.

    • 먼저 10~15분 기다린다 — 대부분은 레지스트리 반영이 그냥 느린 겁니다
    • 같은 번호로 재시도하지 않는다 — E409는 "없는 버전"이 아니라 "이미 업로드된 버전"이란 뜻이에요. 재시도해도 절대 통과 안 됩니다
    • 수 시간 지나도 안 풀리면 — 그때가 진짜 버그 케이스. 그 버전 번호는 포기하고 다음 patch로 범프해서 올리는 게 리포트들에서 나온 답입니다. 갇힌 번호를 풀어낼 수단이 아직 없어요
    • 확인은 npm view <pkg> version --prefer-online이나 registry.npmjs.org/<pkg> JSON의 dist-tags.latest로

    staged에 걸렸을 때 대응 순서 정리

    정리

    • ENEEDAUTH → npm login이 먼저
    • E403 "granular access token with bypass 2fa" → npmjs.com에서 Granular Access Token 발급, bypass 2fa 체크 필수. ~/.npmrc에 넣으면 끝
    • publish 성공인데 버전이 안 보임 + E409 "previously staged" → 실패가 아니라 staged 대기 상태. 10~15분 기다리면 대부분 풀림. 오래 붙어있으면 번호를 버리고 범프
    • 성공 출력을 믿고 바로 확인하러 가면 오히려 당황합니다 — npm publish는 이제 "비동기"라고 생각하는 게 맞는 것 같아요

    하루에 에러 코드를 세 개나 새로 배운 날이었습니다. 라이브러리 배포하다가 같은 벽을 만나신 분들께 도움이 됐으면 합니다.

    728x90
    Posted by 천상나타.