Next.js 배포 실패? Vercel에서 Sentry CLI 오류 해결하기

들어가며

배포 환경에서의 오류는 마치 감기처럼, 언제 올지 모르는 불청객입니다. (저리가)

 

이번 글에서는 평소에는 문제없이 배포되던 프로젝트에서 발생한 예기치 못한 배포 실패 오류로 인한 땀 삐질 모먼트와 이를 해결한 경험을 공유합니다.

 

 

문제 상황 : Sentry CLI 플러그인 에러 (Command failed)

오랫동안 참여하지 않았던 프로젝트에서 간단한 수정 요청을 받았습니다. 단순히 텍스트를 변경하는 수준의 요구사항이었기에, 바로 프로덕션 배포까지 하루 안에 진행되어야 했습니다. 수정사항이 담긴 PR은 문제없이 머지되었고, Staging에서의 QA도 통과되었습니다. 그리고 여느 때처럼, 프로덕션 환경에 배포를 시작했습니다.

 

원래라면 문제없이 배포되어야 하는데, 어찌된 영문인지 배포에 실패하고 말았습니다. 오류의 내용은 다음과 같았습니다.

Failed to compile.
Sentry CLI Plugin: Command failed: /vercel/path0/node_modules/@sentry/cli/sentry-cli releases new 527301f146d0b5b66690997987399984
error: API request failed
  caused by: sentry reported an error: You do not have permission to perform this action. (http status: 403)

 

뜬금없이 발생한 403 Forbidden 에러는 무엇이고, sentry에서의 API request failed라니? 평온했던 마음이 순식간에 혼돈 그 자체가 되었습니다. 오류 로그만 보면, 권한 부족 문제인데.. 이전과 딱히 설정이 달라진 부분도 없었고, sentry의 프로젝트 설정이나 환경 변수 모두 정상적으로 세팅이 되어있었습니다. 게다가 로컬 환경과 github action에서의 빌드는 문제없이 진행되었었습니다. 즉, 명확한 원인을 알 수 없어 당혹스러웠고, 등줄기에 식은 땀이 흘렀습니다.

 

 

문제 해결 : 우선순위 결정

우선적으로, 문제 해결의 우선 순위 정하는 것이 필요했습니다. 당연히 근본적인 원인을 찾고 해결하는 정석적인 방법으로 문제를 해결할 수도 있습니다. sentry-cli의 내부 로직을 분석하거나 sentry, vercel의 모든 설정을 다시 살펴보며 디버깅 하는 방법 등이 있을 것입니다. 하지만 이는 시간이 오래 걸릴 가능성이 높았고, 배포 일정에 맞추는 것이 어려웠습니다.

 

일단은 배포 일정에 맞게 빠르게 배포를 진행할 수 있는 우회 방법을 찾아 해결하는 것이 비즈니스적으로 더 중요하다고 생각하여 임시 방편이라도 배포 실패를 해결하고, 원활하게 배포가 될 수 있도록 방법을 찾기 시작했습니다.

 

 

해결 과정

Sentry-cli Plugin: Command failed 라는 키워드로 구글링을 조금 해보니 비슷한 사례들을 확인할 수 있었습니다. 대부분의 사례에서 Sentry CLI가 빌드 실패의 원인으로 작용했으며, 이를 해결하기 위한 방법으로 Sentry Webpack Plugin의 errorHandler 옵션을 활용할 수 있다는 점을 발견했습니다. 이에 따라 Sentry의 공식 문서와 플러그인 옵션 문서를 검토하며 다음과 같은 해결 방법을 적용했습니다.

 

찾아봤던 문서들

https://github.com/getsentry/sentry-cli/issues/1232

Sentry CLI Plugin: Command failed: API request failed · Issue #1232 · getsentry/sentry-cli

https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/#extend-sentry-webpack-plugin-options

Manual Setup | Sentry for Next.js

https://github.com/getsentry/sentry-webpack-plugin#options

GitHub - getsentry/sentry-webpack-plugin: Repo moved to https://github.com/getsentry/sentry-javascript-bundler-plugins. Please o

 

반복해서 보이는 비슷한 이슈들

https://github.com/getsentry/sentry-cli/issues/1626

https://community.fly.io/t/deployment-failing-in-github-actions-unable-to-pass-env-to-deploy-command/6099

https://giters.com/getsentry/sentry-webpack-plugin/issues/236

(구글링하다보면..위 3개 링크 뿐 아니라 비슷한 이슈가 더 많이 나옵니다.)

 

 

적용한 해결 방법 - next.config에서 설정 코드 수정

위 문서들을 참고하여, next.config.js 파일을 수정하여 sentry-cli의 오류가 빌드를 중단하지 않도록 설정을 추가했습니다. 아래 코드는 sentry-cli 오류를 빌드 중단 대신 경고로 처리하도록 구성한 것입니다. 커스터마이징한  errorHandler  옵션은 빌드 과정에서 발생한 오류 메세지를 경고로 전환해, 빌드가 계속 진행되도록 합니다. next.config.js의 수정된 주요 내용입니다.

module.exports = withSentryConfig(
  module.exports,
  {
    org: '회사명',
    project: '프로젝트 명',
    silent: true,
    errorHandler: (err, invokeErr, compilation) => {
      compilation.warnings.push('Sentry CLI Plugin: ' + err.message);
    },
  },
  {
    widenClientFileUpload: false,
    transpileClientSDK: false,
    tunnelRoute: '/monitoring',
    hideSourceMaps: true,
    automaticVercelMonitors: true,
  }
);

 

위 코드 적용 결과

수정 후, 다시 빌드를 실행했을 때 오류 메세지는 여전히 표시되었으나 빌드가 멈추지 않았고, 정상적으로 vercel에 배포가 완료되었습니다.

수정 전

계속 빨간불에서..

수정후

얼마 만에 보는 파란 불인지..

 

참고 사항

위 코드에서의 next.js는 12버전이었고, sentry는 7.110 버전이었습니다.

다른 프로젝트에서는 14버전의 next.js를 사용하고 있었고, sentry는 8.26버전이었습니다.

다른 프로젝트에서는 아래와 같이 설정을 수정해두었습니다.

export default withSentryConfig(nextConfig, {
  org: '회사명',
  project: '프로젝트명',
  authToken: process.env.SENTRY_AUTH_TOKEN,
  silent: true,
  unstable_sentryWebpackPluginOptions: {
    errorHandler: err => {
      console.warn(`Sentry CLI Plugin Error: ${err.message}`);
    },
  },
});

 

 

트러블 슈팅 후기 및 회고

1. 작은 실수로 더 늦어버린 해결

next.config에 옵션 설정을 바꿀 때, 다소 어처구니 없는 실수를 저질렀었습니다. errorHandler 설정을 userSentryWebpackPluginOptions 관련 argument에 세팅을 했어야 하는데, sentryOptions 관련 argument에 적어버렸었습니다. (대체 왜 그랬을까요..)

module.exports = withSentryConfig(
  module.exports,
  {
    org: '회사명',
    project: '프로젝트 명',
    silent: true,
  },
  {
    widenClientFileUpload: false,
    transpileClientSDK: false,
    tunnelRoute: '/monitoring',
    hideSourceMaps: true,
    automaticVercelMonitors: true,
    errorHandler: (err, invokeErr, compilation) => {
      compilation.warnings.push('Sentry CLI Plugin: ' + err.message);
    },
  }
);

(이러니 당연히 안되지...)

다급함과 당황 속에서 급하게 처리하려고 하다 보니 발생한 실수였고, 타입스크립트가 적용되지 않아서 더욱 헷갈렸던 것 같기도 합니다.

 

2. 근본적인 해결되지 않은 의문들

이전에는 왜 문제없이 배포가 잘 되었을까. 일단 next.js나 sentry의 버전은 이전과 완전히 동일했었습니다. 무엇이 api request failed를 일으킨 것인지도 아직 모르는 부분이고, 로컬과 staging 배포까지도 문제가 없었는데, release에서만 실패한 것도 의문이었습니다.

추가로..

여기 블로그를 보니, .sentryclirc 관련 이슈라고 하는데, 역시나 이것도 왜..?라는 의문이 말끔히 사라지지는 않았습니다. 시간이 생기면 좀 더 분석해보고 .sentryclirc를 gitignore에서 제거하는 것으로 문제가 해결되는지 확인해보아야 할 것 같습니다.

 

3. 빠른 우선순위 설정

시간적 여유를 충분히 가진 상황에서라면 문제 해결에 대한 접근 방법이 달랐을 것입니다. 다만, 개발자가 아니라면 배포 (빌드)가 실패한 원인이 무엇인지, 어떻게 해결하는 게 좋은 방법인지 궁금해하거나 신경쓰지 않을 수도 있습니다. 게다가 비즈니스적으로, 변경 내용이 빠르게 실제 사용자에게 반영이 되어야 한다면 더더욱 '변경 사항이 실제 서비스에 잘 반영되었는가'만이 중요할 것입니다. 물론, 건강하게 제품 개발을 계속해서 이어가려면 이대로 끝나서는 안될 것입니다. 긴급 조치 이후에는 무엇이 잘못되었는지 분명하게 원인을 파악하고, 같은 문제가 재발하지 않도록 해야할 것입니다.

 

 

마무리

이번 글에서는 배포 상황에서의 오류 발생과 처리 방법에 대한 경험을 공유해보았습니다. 관련해서 이슈 혹은 stackoverflow 내용들이 중복해서 보이는 것으로 보아, 사실 생각보다 많은 분들이 비슷한 오류를 경험한 것은 아닐까 하는 생각이 들어 관련 내용을 작성해보았습니다.

 

혹시 같은 sentry-cli 에러 관련해서 보다 나은 해결 방법을 알고 계신다면, 댓글로 남겨주시면 감사하겠습니다! 😊