[Sentry][프론트엔드] source_file_lookup_result는 found인데 source_map_lookup_result만 not_found일 때 sourceMappingURL과 업로드 이름을 어떤 순서로 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] source_file_lookup_result는 found인데 source_map_lookup_result만 not_found일 때 sourceMappingURL과 업로드 이름을 어떤 순서로 다시 보나

Sentry source-map-debug API를 보다 보면 JS 파일 artifact는 분명히 맞는데 source map만 못 찾는 패턴이 나온다. 2026년 7월 9일 기준 Sentry 공식 문서를 다시 보면, API는 `source_file_lookup_result`와 `source_map_lookup_result`를 따로 보여 주고, `matching_source_map_name`과 `source_map_reference`로 Sentry가 기대한 map 이름도 함께 준다. 동시에 legacy sourcemap 문서는 배포된 JS의 `sourceMappingURL`이 실제로 남아 있는지, 그리고 업로드한 map artifact 이름이 그 값과 같은지 확인하라고 적고 있다. 이 글은 source file lookup은 성공했는데 source map lookup만 실패할 때 무엇부터 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 source_file_lookup_result=found인데 source_map_lookup_result=not_found가 나오면, JS frame 이름 축보다 sourceMappingURL과 map artifact 이름 축을 먼저 다시 보는 편이 맞다. JS 파일을 찾았다는 뜻은 frame 경로와 file artifact 이름 축은 어느 정도 맞았다는 신호이기 때문이다. 이 경우 release나 dist보다 source map reference와 업로드 이름 대응이 먼저다.

이미 source_file_lookup_result not_found 글이 file 쪽 lookup 실패를 다뤘고, tilde 정규화와 deploy prefix 글이 prefix 축을 다뤘다면, 이번 글은 file lookup은 통과했는데 map lookup만 남는 분기다.

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

현장에서 자주 나오는 오해는 세 가지다. 첫째, source map도 같은 prefix 규칙이면 자동으로 따라온다고 생각한다. 둘째, JS file artifact가 보이니 map artifact 이름도 맞을 것이라고 가정한다. 셋째, map lookup 실패인데도 release 재생성이나 dist 변경부터 다시 시작한다.

하지만 source-map-debug API는 file과 map lookup을 별도 필드로 나눈다. 또 같은 응답 안에 matching_source_map_name과 source_map_reference를 넣어 어떤 map 이름을 기대했는지 보여 준다. 즉 file artifact 이름과 map artifact 이름은 서로 다른 검증 축이다. JS 파일 lookup이 성공해도 map 파일 이름이나 sourceMappingURL이 어긋나면 map lookup만 따로 실패할 수 있다.

Sentry 문서는 배포된 JS 파일에 sourceMappingURL이 실제로 남아 있는지 확인하라고 하고, 업로드 artifact 이름도 그 reference가 해석되는 값과 같아야 한다고 적는다. 이 조건을 놓치면 CDN이나 minifier가 주석을 바꾼 뒤 map lookup만 조용히 실패하는 상황을 만들기 쉽다.

• 증상: JS file artifact는 보이는데 map lookup만 실패한다.
• 실패: file artifact 이름이 맞으니 map 이름도 맞을 것이라고 본다.
• 막힘: sourceMappingURL 값을 실제 배포 파일에서 다시 확인하지 않는다.
• 누락: matching_source_map_name과 업로드 artifact 이름을 같은 표로 안 남긴다.

증상	먼저 볼 것	판단 기준
file=found / map=not_found	sourceMappingURL	배포된 JS가 어떤 map을 가리키는지 본다
matching_source_map_name이 다르다	업로드 map artifact 이름	reference와 같은 규칙인지 본다
sourceMappingURL이 아예 없다	배포 pipeline	주석 제거 또는 rewrite 여부를 본다

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

가장 빠른 순서는 네 단계다. 먼저 source-map-debug API에서 matching_source_map_name과 source_map_reference를 확인한다. 두 번째로 배포된 JS 파일 마지막 줄의 sourceMappingURL이 무엇인지 본다. 세 번째로 실제 업로드한 map artifact 이름이 그 reference가 해석되는 값과 같은지 비교한다. 마지막으로 그 뒤에야 prefix, release, dist를 다시 본다.

1. matching_source_map_name을 확인한다.
2. 배포된 JS의 sourceMappingURL 값을 확인한다.
3. 업로드한 source map artifact 이름과 대조한다.
4. 그래도 다르면 prefix, release, dist를 다시 본다.
5. 배포 전에는 source map upload와 실제 JS 파일 검사 결과를 같이 남긴다.

이 순서가 중요한 이유는 문제 크기를 빠르게 줄이기 때문이다. file lookup이 이미 found라면 프레임 경로와 JS artifact 이름 축은 어느 정도 맞는다. 그렇다면 남은 주된 의심은 map file reference다. 이 상태에서 release 전체를 다시 만지는 것은 범위를 너무 넓게 잡는 셈이다.

운영 메모 예시

source_file_lookup=found
source_map_lookup=not_found
source_mapping_url=app.min.js.map
matching_source_map_name=~/assets/app.min.js.map
uploaded_map_name=~/assets/app.min.js.map

이렇게 적어 두면 map lookup 실패가 다시 나와도 release 이름부터 되짚지 않고 곧바로 source map 이름 축으로 들어갈 수 있다. JS artifact를 찾은 사실을 적극적으로 활용해야 한다.

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

첫 자료는 source-map-debug API 응답 스키마다. 여기서는 같은 frame에 대해 `source_file_lookup_result`와 `source_map_lookup_result`가 별도 필드로 나온다는 점이 중요하다.

Sentry source-map-debug API는 source file lookup과 source map lookup 결과를 별도 필드로 보여 준다.

이 구분 덕분에 JS 파일 이름은 맞았지만 map 파일 이름만 못 찾는 상황을 따로 좁힐 수 있다. bundle 전체를 다시 의심할 필요가 없는 경우가 생긴다.

두 번째 자료는 같은 API가 내려주는 `matching_source_map_name`과 `source_map_reference` 필드다. Sentry가 어떤 map 이름을 기대하는지 직접 보여 주기 때문에 source map 파일명 대조의 출발점이 된다.

Sentry source-map-debug API는 기대한 source map 이름과 sourceMappingURL reference를 같이 보여 준다.

즉 JS frame 경로가 맞아도 map 파일명이 다르거나 `sourceMappingURL`이 다른 위치를 가리키면 map lookup만 실패할 수 있다. file과 map의 실패 원인을 따로 읽어야 한다.

세 번째 자료는 legacy uploading methods 문서의 `Verify sourceMappingURL is present` 구간이다. 배포된 JS 파일 마지막 줄의 `sourceMappingURL`이 실제로 남아 있는지 먼저 확인하라고 적고 있다.

Sentry 문서는 배포된 JS 파일에 sourceMappingURL이 실제로 남아 있는지 먼저 확인하라고 안내한다.

이 단계가 빠지면 JS 파일 artifact는 맞는데 source map 이름만 틀린 상황을 놓치기 쉽다. 특히 CDN이나 minify 단계가 주석을 건드리면 JS lookup은 성공해도 map lookup은 실패할 수 있다.

네 번째 자료는 artifact 이름과 `sourceMappingURL` 값이 일치해야 한다는 설명이다. 문서는 map 파일 이름도 JS 파일이 참조하는 값과 같은 규칙으로 업로드해야 한다고 적고 있다.

Sentry 문서는 업로드한 source map 이름이 배포된 JS의 sourceMappingURL이 가리키는 값과 같아야 한다고 설명한다.

그래서 `source_file_lookup_result=found`인데 `source_map_lookup_result=not_found`라면 JS 파일명보다 map reference와 업로드 이름을 먼저 다시 비교하는 편이 맞다.

실무에서는 found/not_found 조합을 표로 먼저 나누는 편이 빠르다. source file만 맞고 map만 안 맞는 상황은 upload 경로와 `sourceMappingURL` 쪽으로 바로 좁혀야 한다.

source file lookup과 source map lookup 조합별로 먼저 볼 포인트를 나눈 표다.

이 표를 기준으로 보면 release나 dist를 다시 보는 시점이 뒤로 밀린다. 먼저 map reference와 업로드 이름을 맞춰야 한다. 이미 tilde 정규화와 deploy prefix 글이 prefix 축을 다뤘다면, 이번 표는 map 이름 축을 따로 좁히는 후속편이다.

마지막 자료는 sourceMappingURL과 업로드 이름을 같은 메모에 붙인 예시다. JS 파일이 어떤 map 이름을 참조하는지와 Sentry에 어떤 이름으로 업로드했는지를 한눈에 비교해야 한다.

sourceMappingURL과 업로드 artifact 이름을 대조하는 예시다.

이 정도 메모가 있으면 map lookup만 실패했을 때 바로 source map 이름 축으로 좁혀 들어갈 수 있다. JS file lookup은 이미 통과했으므로 문제를 더 작게 나눌 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 JS file lookup 성공을 전체 sourcemap 연결 성공처럼 해석하는 것이다. 두 번째 리스크는 CDN이나 minifier가 sourceMappingURL을 바꿨는데 배포 파일을 직접 확인하지 않는 것이다. 세 번째 리스크는 map artifact 이름 불일치를 dist나 release 문제와 섞는 것이다.

운영 전에 확인할 때는 최소한 sourceMappingURL 값, 업로드 map artifact 이름, matching_source_map_name을 같은 메모에 남기는 편이 좋다. 그래야 lookup 실패가 file 축인지 map 축인지 몇 분 안에 갈라진다.

• JS file lookup 성공은 map lookup 성공 보장이 아니다.
• sourceMappingURL 값과 map artifact 이름을 같이 본다.
• map 이름 축을 먼저 좁힌 뒤에 prefix와 dist를 본다.

6. 결론

Sentry에서 source_file_lookup_result=found인데 source_map_lookup_result=not_found가 나오면, JS frame 경로보다 sourceMappingURL과 source map artifact 이름을 먼저 다시 보는 편이 맞다. file lookup은 이미 통과했기 때문에 map reference 축이 더 유력한 원인이다. 배포된 JS가 어떤 map을 가리키는지와 Sentry가 어떤 map 이름을 기대하는지 맞춰 보면 문제를 훨씬 짧게 줄일 수 있다.

이 기준은 바로 앞 단계인 tilde 정규화와 deploy prefix 글 위에서 동작하는 다음 분기다. prefix 축이 맞아도 map 이름 축은 따로 틀릴 수 있다.

그리고 map 이름 축까지 맞았는데도 이벤트 화면에서 원본 소스가 비어 있다면, 이제는 경로가 아니라 sourcesContent와 original source 업로드 축으로 이동해야 한다. 그 다음 분기는 source file과 source map은 found인데 original source만 비는 경우 점검 글에서 이어진다.

• file found와 map found는 별도 체크다.
• sourceMappingURL과 map artifact 이름을 먼저 대조한다.
• release와 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/troubleshooting_js/legacy-uploading-methods/