[Sentry][프론트엔드] source-map-debug API에서 release_has_some_artifact는 true인데 source_file_lookup_result가 not_found일 때 파일명과 prefix를 어떤 순서로 다시 확인하나

IT 리서치 노트

[Sentry][프론트엔드] source-map-debug API에서 release_has_some_artifact는 true인데 source_file_lookup_result가 not_found일 때 파일명과 prefix를 어떤 순서로 다시 확인하나

Sentry source-map-debug API를 보면 `release_has_some_artifact=true`인데도 `source_file_lookup_result=not_found`가 나오는 경우가 있다. 이때 많은 팀이 upload 전체를 다시 의심하거나 release 이름부터 다시 맞추는데, 2026년 7월 6일 기준 Sentry 공식 문서를 다시 보면 이런 패턴은 release 연동 자체보다 frame 경로와 artifact 이름, prefix 정규화가 안 맞는 경우가 더 많다. 이 글은 그 확인 순서를 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 release_has_some_artifact=true는 release에 연결된 artifact가 있다는 뜻일 뿐이고, frame이 그 artifact를 찾았다는 뜻은 아니다. 이 상태에서 source_file_lookup_result=not_found가 나오면 release 이름보다 먼저 abs_path, 업로드 파일명, url-prefix 또는 strip-prefix, 경로 정규화 순서를 다시 보는 편이 맞다.

이미 release artifact gap 글이 상위 플래그를 다뤘다면, 오늘 글은 lookup 단계다. 또 rewriteFrames mixed path 글과 CDN 경로 drift 글의 사이를 메우는 분기라고 보면 된다.

2. 어디서 실제로 막히는가

현장에서 자주 나오는 오해는 세 가지다. 첫째, release artifact가 있으니 lookup도 성공해야 한다고 생각한다. 둘째, upload bundle이 보이니 파일명과 prefix는 맞을 것이라고 가정한다. 셋째, source_file_lookup_result가 not_found인데도 dist부터 바꾸기 시작한다.

Sentry source-map-debug API는 release 과정과 frame lookup 과정을 같은 응답에서 따로 보여 준다. 따라서 release_has_some_artifact가 true라는 말은 release에 매달린 artifact는 있다는 뜻이고, lookup이 실패했다면 이벤트 frame의 abs_path가 업로드 artifact 이름과 못 만난 상태일 가능성이 높다. troubleshooting guide도 minified file과 source map 둘 다 있어야 한다고 설명하는데, 이 말은 업로드 존재 자체와 실제 적용 경로가 또 다른 층이라는 뜻이기도 하다.

특히 CDN prefix, ~ prefix, custom base path, hash 파일명, rewriteFrames가 한 코드베이스에 같이 들어가면 upload는 성공했는데 lookup만 not_found가 날 수 있다. 이 경우 release를 다시 만드는 것보다 frame path와 artifact 이름이 어떤 규칙으로 이어져야 하는지부터 정리하는 편이 빠르다.

• 증상: release artifact는 보이는데 event frame은 풀리지 않는다.
• 실패: release 이름부터 다시 손대고 frame path는 안 본다.
• 막힘: prefix와 strip-prefix를 기록하지 않아 비교가 안 된다.
• 누락: rewriteFrames나 CDN path 정규화를 dist보다 뒤에 보지 않는다.

증상	먼저 볼 곳	판단 기준
release artifact는 있다	frame abs_path와 artifact 이름	실제 파일명이 대응되는지 본다
lookup만 not_found다	url-prefix, strip-prefix	protocol/hostname/base path가 맞는지 본다
경로 스킴이 섞인다	rewriteFrames, CDN path	app:///와 https://가 같은 파일을 가리키는지 본다

3. 실무에서 적용하는 순서

실무에서는 네 단계가 가장 짧다. 먼저 source-map-debug API에서 frame의 abs_path를 그대로 복사해 업로드 artifact 이름과 비교한다. 두 번째로 CLI에서 어떤 --url-prefix 또는 --strip-prefix로 업로드했는지 확인한다. 세 번째로 앱 런타임에서 rewriteFrames나 CDN path rewrite가 있는지 본다. 네 번째로 그 다음에야 dist를 확인한다.

1. event frame의 abs_path를 먼저 고정한다.
2. 업로드 파일명과 실제 hash 파일명을 대조한다.
3. url-prefix 또는 strip-prefix를 다시 확인한다.
4. rewriteFrames와 CDN path normalization을 확인한다.
5. 마지막에 dist를 본다.

왜 이 순서가 맞냐면 release_has_some_artifact=true가 이미 release 연동 축 일부를 통과했다는 신호이기 때문이다. 아직 lookup이 not_found라면 남은 의심은 frame path와 artifact 경로를 맞추는 층에 더 가깝다. dist는 같은 release 안에서 variant를 구분하는 값이라서, 파일명과 prefix가 틀린 상황에서는 dist를 손봐도 바로 해결되지 않는 경우가 많다.

점검 메모 예시

abs_path=https://cdn.example.com/assets/app.4e91c.js
uploaded_artifact=~/assets/app.4e91c.js
url_prefix=~/assets
strip_prefix=/workspace/apps/web/dist
rewrite_frames=app:/// -> https://cdn.example.com/assets
dist_checked_last=true

이렇게 남겨 두면 upload 성공 로그가 있어도 lookup not_found를 독립된 문제로 다룰 수 있다. 문제를 좁히는 순서가 명확해질수록 같은 증상을 반복 재현하는 시간이 짧아진다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 source-map-debug API 응답 스키마다. 여기서는 release 쪽 과정과 source file lookup 결과를 같은 응답에서 분리해 보여 준다는 점이 중요하다.

Sentry source-map-debug API는 release 연동과 source file lookup 결과를 같은 응답에서 따로 보여 준다.

즉 release_has_some_artifact=true라고 해서 frame lookup까지 자동으로 성공했다는 뜻은 아니다. 이미 release artifact gap 글이 상위 플래그 분리를 다뤘다면, 이번 글은 그다음 단계인 lookup not_found 분기다.

두 번째 화면은 troubleshooting guide의 기본 조건 설명이다. Sentry가 stack trace를 제대로 풀려면 minified file과 대응 source map이 올라가 있어야 한다고 먼저 적고 있다.

Sentry troubleshooting guide는 minified file과 source map 둘 다 있어야 stack trace를 풀 수 있다고 설명한다.

lookup not_found는 대개 이 두 파일이 아예 없다는 뜻보다, 이벤트의 frame 경로와 업로드 artifact 이름이 서로 못 만났다는 뜻으로 보는 편이 더 정확하다.

세 번째 자료는 CLI 업로드 문서의 artifact bundles 설명이다. 여기서는 bundle이 업로드됐는지와 Source Maps 화면에서 어떤 탭을 확인해야 하는지를 보여 준다.

Sentry CLI 문서는 artifact bundle 업로드 여부를 Source Maps 화면에서 확인하라고 안내한다.

이 단계가 통과됐다면 upload 실패보다 경로 해석 실패를 먼저 의심할 수 있다. bundle 존재와 frame lookup 성공은 다른 단계다.

네 번째 화면은 legacy uploading methods 문서의 `~` prefix 설명이다. 여기서는 protocol과 hostname이 달라도 path가 맞으면 artifact를 찾게 하려면 어떤 prefix를 쓰는지 보여 준다.

Sentry legacy sourcemap 문서는 `~` prefix가 protocol과 hostname을 무시하고 path 기준으로 artifact를 찾게 한다고 설명한다.

source_file_lookup_result가 not_found일 때 이 문장이 중요한 이유는, release artifact는 있어도 frame의 abs_path와 artifact 이름을 이어 주는 prefix가 틀리면 lookup이 실패할 수 있기 때문이다. CDN 경로와 hash drift 글과도 직접 연결된다.

source-map-debug 응답을 숫자 대신 구조로 한 번 보면 분기가 빨라진다. 상위 플래그는 괜찮은데 lookup만 not_found인 상태를 따로 읽어야 한다.

release artifact는 있지만 source file lookup만 not_found인 source-map-debug 응답 예시다.

이 예시라면 upload 전체를 다시 의심하기보다, frame abs_path와 artifact 이름, url-prefix 또는 strip-prefix를 먼저 대조하는 편이 맞다. dist는 그 다음 축이다.

이 표는 lookup not_found일 때 어떤 순서로 다시 대조할지 정리한 것이다. release 이름부터 다시 헤매기보다 파일명과 prefix를 먼저 대조하는 편이 빠르다.

release_has_some_artifact=true 상태에서 source_file_lookup_result not_found를 좁히는 점검 순서표다.

이 순서대로 보면 frame path 문제와 release artifact 존재 문제를 섞지 않게 된다. mixed path scheme 글, dist 운영 기준 글과 이어 읽기 좋다.

마지막 자료는 prefix와 strip-prefix를 남기는 업로드 메모 예시다. 실제 값은 프로젝트마다 다르지만 어떤 축을 남겨야 하는지는 비슷하다.

prefix와 strip-prefix를 다시 확인할 때 남겨 둘 sentry-cli 업로드 메모 예시다.

이 정도 로그를 남기면 lookup not_found가 다시 나와도 어떤 prefix로 올렸는지와 frame path가 어떤 형태였는지 비교가 빨라진다.

5. 주의사항과 리스크

첫 번째 리스크는 release artifact가 존재한다는 이유로 경로 문제를 뒤로 미루는 것이다. 두 번째 리스크는 CLI 업로드 옵션을 남기지 않아 어떤 prefix로 올렸는지 모르는 상태가 되는 것이다. 세 번째 리스크는 dist mismatch와 path mismatch를 한 문제로 묶는 것이다.

운영 전에 확인할 때는 최소한 frame abs_path, uploaded artifact 이름, url-prefix, strip-prefix, dist를 같은 기록에 남기는 편이 좋다. 그래야 source_file_lookup_result가 not_found일 때 어떤 층에서 갈렸는지 바로 말할 수 있다.

• release artifact 존재와 lookup 성공은 다른 단계다.
• 파일명과 prefix가 dist보다 먼저다.
• rewriteFrames와 CDN path 정규화는 lookup not_found의 흔한 원인이다.

6. 결론

Sentry source-map-debug API에서 release_has_some_artifact=true인데 source_file_lookup_result=not_found가 나오면, release 이름보다 먼저 frame abs_path와 artifact 파일명, prefix를 다시 대조하는 편이 맞다. release artifact는 있는데 실제 frame이 그 파일을 못 찾는 상태이기 때문이다. 파일명과 prefix를 먼저 맞추고, 그다음에 rewriteFrames와 dist를 보면 lookup not_found를 훨씬 짧게 좁힐 수 있다.

만약 파일명과 prefix는 얼추 맞는데도 event frame URL 자체가 매번 달라진다면, debug_id는 맞는데 abs_path canonicalization이 흔들릴 때 rewriteFrames와 frame URL을 대조하는 후속 글이 바로 다음 단계다. lookup not_found 뒤에 남는 경로 정규화 문제를 더 좁게 다룬다.

• release artifact 존재는 lookup 성공 보장이 아니다.
• 파일명과 prefix를 먼저 본다.
• dist는 그다음 축이다.

7. 참고 링크

1. https://docs.sentry.io/api/events/get-debug-information-related-to-source-maps-for-a-given-event/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/
4. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/