[Sentry][프론트엔드] source_map_lookup_result는 found인데 라인 매핑이 틀릴 때 sourcesContent와 column mapping을 어느 순서로 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] source_map_lookup_result는 found인데 라인 매핑이 틀릴 때 sourcesContent와 column mapping을 어느 순서로 다시 보나

Sentry에서 source_file_lookup_result와 source_map_lookup_result가 둘 다 found인데도 이벤트 화면의 코드 줄이 어색하거나 column 위치가 틀어지는 경우가 있다. 이때는 prefix나 artifact 이름부터 다시 뒤지기 쉽지만, 2026년 7월 11일 기준 공식 문서를 다시 보면 그 다음 분기는 sourcesContent, original source files, sourceRoot, local line·column validate 쪽에 더 가깝다. 이 글은 found/found까지는 통과했는데 라인 매핑이 이상할 때 무엇부터 다시 보는 편이 맞는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 source_map_lookup_result=found 상태에서 라인 매핑이 이상하면, 먼저 sourcesContent와 original source files 유무를 보고, 그다음 sourceRoot, 마지막에 local line·column validate로 내려가는 편이 맞다. found/found는 경로와 업로드 이름 축을 어느 정도 통과했다는 뜻일 뿐, 원본 코드 재료와 매핑 품질까지 보장하지는 않는다.

즉 오늘 분기는 '찾았느냐'보다 '찾은 map이 정확하냐'의 문제다. 이미 source_map_lookup_result not_found 글, original source empty 글, partial original source gap 글을 따라왔다면, 이번 글은 그다음 단계의 line·column 품질 분기다.

2026-07-12 후속 글인 sourceMappingURL은 맞는데 CDN이 map 파일을 압축하거나 차단할 때 scraping status와 uploaded artifact를 나누는 방법도 함께 보면 좋다. 이 글이 found/found 뒤의 line·column 품질 축이라면, 후속 글은 artifact 이름 매칭은 통과했는데 live fetch scraping만 실패하는 경우를 따로 분리한다.

그리고 found/found와 sourcesContent, sourceRoot까지는 대체로 맞는데 local validate에서 column mismatch만 남는다면 더 좁은 후속 글인 source map과 release는 맞는데 local validate만 column mismatch일 때 어떤 transform부터 다시 보는지 정리한 글이 바로 다음 단계다. 이 글이 품질 축 전체를 나눈다면, 후속 글은 그 안에서도 build transform 순서를 더 잘게 쪼갠다.

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

현장에서 자주 생기는 혼선은 네 가지다. 첫째, source file과 source map이 모두 found면 sourcemap 문제는 끝났다고 본다. 둘째, 코드 줄이 어긋나면 release나 dist, prefix를 다시 맞추려 한다. 셋째, sourcesContent가 없는 map과 column mapping이 틀린 map을 같은 문제로 취급한다. 넷째, local validate를 건너뛰고 서버 쪽 설정만 계속 바꾼다.

Sentry 문서를 이어 읽으면 분기가 더 세밀하다. source-map-debug API는 file과 map lookup 결과를 보여 주지만, troubleshooting 문서는 sourcesContent 유무를 먼저 확인하라고 말한다. legacy uploading methods 문서는 sourcesContent가 없으면 original source files를 추가로 제공해야 한다고 적는다. TypeScript guide는 sourceRoot가 build path 해석에 영향을 준다는 예시를 제공한다. 즉 found/found 뒤에도 최소 세 개의 품질 축이 남아 있다.

그래서 line mismatch를 release 축으로 되돌리면 작업 범위만 커진다. 전체 원본 코드가 비는 문제인지, 일부 파일 경로 해석이 이상한 문제인지, line은 맞지만 column만 틀린 문제인지 먼저 나눠야 한다. 이 세 가지는 수정 위치가 서로 다르기 때문이다. 첫 번째는 map payload 또는 보조 업로드, 두 번째는 sourceRoot나 sources 해석, 세 번째는 실제 transform 단계와 local mapping validate가 더 가깝다.

• 증상: found/found인데도 이벤트 화면의 코드 줄이나 column 위치가 틀어진다.
• 실패: release, dist, prefix 축으로 되돌아간다.
• 막힘: sourcesContent, sourceRoot, local validate를 한 번에 다 바꾼다.
• 누락: original source files 보조 업로드 여부를 확인하지 않는다.

질문	먼저 볼 값	이유
원본 코드 재료가 충분한가	sourcesContent, original source files	map 품질 진단의 출발선이다
특정 파일만 틀어지나	sourceRoot, sources 경로	부분 경로 해석 문제일 수 있다
column만 어긋나나	local line/column validate	transform 단계 품질 문제를 좁힌다

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

가장 덜 꼬이는 순서는 다섯 단계다. 먼저 source-map-debug API에서 file과 map lookup이 둘 다 found인지 확인한다. 두 번째로 실제 source map payload에 sourcesContent가 있는지 본다. 세 번째로 없으면 original source files를 보조 업로드했는지 확인한다. 네 번째로 일부 파일만 이상하면 sourceRoot와 sources 경로를 비교한다. 마지막으로 local line·column validate를 돌려 column mismatch가 실제 build 결과인지 확인한다.

1. file/map lookup이 둘 다 found인지 먼저 고정한다.
2. source map payload의 sourcesContent를 확인한다.
3. 필요하면 original source files 업로드 여부를 본다.
4. 특정 파일만 이상하면 sourceRoot와 sources 경로를 비교한다.
5. 마지막에 local line·column validate로 품질을 검증한다.

이 순서가 좋은 이유는 한 단계가 다음 단계를 뒤집지 않기 때문이다. sourcesContent가 없으면 column mismatch를 따질 기반이 약하다. sourceRoot가 잘못되면 일부 파일만 이상하게 보일 수 있다. local column validate에서만 틀리면 build transform 또는 minifier 단계 문제일 확률이 높다. 이 해석은 공식 문서가 각각 분리해서 설명하는 축들을 운영 순서로 묶은 추론이다.

운영 메모 예시

file_lookup=found
map_lookup=found
sourcesContent_present=true
original_source_files_uploaded=true
sourceRoot=/ 
local_line_mapping=pass
local_column_mapping=mismatch

실행할 때는 먼저 source-map-debug API 결과를 저장하고, 실제 배포된 map 파일에서 sourcesContent와 sources 배열을 연다. 그다음 local validate 스크립트나 번들러 테스트로 특정 line·column을 찍어 보고, 마지막으로 sourceRoot를 바꾼 preview build를 따로 비교한다. 이 과정을 분리해야 한 번의 수정으로 세 축을 동시에 건드리는 실수를 줄일 수 있다.

• API 결과와 실제 map payload를 같은 이슈 번호로 묶는다.
• preview build에서 sourceRoot 조정 실험을 따로 돌린다.
• local line·column validate 결과를 마지막 판단 근거로 남긴다.

핵심은 found/found를 성공으로 끝내지 않는 것이다. 그다음부터는 원본 포함 여부와 매핑 품질이라는 별도 레이어가 열린다.

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

첫 자료는 source-map-debug API 예시 응답이다. 여기서는 source_file_lookup_result와 source_map_lookup_result가 둘 다 found인 상태를 보여 준다. 오늘 글은 바로 이 상태인데도 이벤트 화면의 라인 매핑이 이상할 때 어디로 이동해야 하는지 다룬다.

source-map-debug API에서 file과 map lookup이 모두 found라도 그다음 품질 문제는 남을 수 있다.

즉 이 단계는 경로와 업로드 이름 축이 대체로 통과했다는 뜻일 뿐, 원본 코드 포함 여부나 line·column 품질까지 보장하지는 않는다. found/found를 '끝'으로 읽으면 그다음 진단이 전부 늦어진다.

두 번째 자료는 Sentry JavaScript sourcemap troubleshooting 문서다. 이 페이지는 source map이 원본 소스 코드를 sourcesContent에 포함하는지 먼저 확인하라고 안내한다. found/found인데 라인이 어긋날 때도 전체 원본 포함 여부를 먼저 보는 이유가 여기 있다.

Sentry troubleshooting 문서는 source map 안에 sourcesContent가 있는지 먼저 확인하라고 안내한다.

즉 일부 라인이 이상하더라도 가장 먼저 할 일은 path를 다시 비교하는 것이 아니라 map payload 안에 원본 코드 재료가 들어 있는지 확인하는 것이다. sourcesContent가 비어 있으면 이후 column mapping 진단은 출발선부터 흔들린다.

세 번째 자료는 legacy uploading methods 문서다. Sentry는 source map에 sourcesContent가 없으면 original source files를 추가로 제공해야 한다고 적는다. 즉 line mismatch 진단으로 바로 내려가기 전에, 애초에 Sentry가 보여 줄 원본 파일이 충분한지도 같이 봐야 한다.

Sentry 문서는 sourcesContent가 없을 때 original source files를 보조 업로드하라고 설명한다.

따라서 found/found인데도 코드 줄이 비정상적으로 보이면 '경로는 맞고 재료가 부족한 상태'일 가능성을 먼저 배제해야 한다. 이 분기를 건너뛰면 sourceRoot나 column mapping을 바꿔도 효과가 없을 수 있다.

네 번째 자료는 TypeScript sourcemap 업로드 가이드다. 이 페이지는 sourceRoot를 어떻게 둘지와 build path prefix를 어떻게 해석할지를 예시로 보여 준다. file과 map lookup은 통과했는데 특정 줄이나 특정 파일의 매핑만 어긋나는 경우, 이 축을 뒤에서 확인해야 한다.

TypeScript 가이드는 sourceRoot가 경로 해석과 이슈 grouping 품질에 영향을 준다고 보여 준다.

즉 sourceRoot는 found/found 이전 문제보다 found/found 이후의 품질 문제에서 더 자주 등장한다. 모든 것이 not_found인 상황과 일부 줄만 이상한 상황을 같은 축으로 보면 수정 범위가 쓸데없이 커진다.

실무에서는 found/found 이후 진단을 표로 묶어 두는 편이 좋다. 아래 표는 sourcesContent, original source files, sourceRoot, local column validate를 어떤 순서로 다시 보는지 정리한 것이다.

source-map lookup은 통과했는데 라인 매핑이 이상할 때의 Sentry triage 표다.

이 표처럼 보면 128번 글의 not_found 축, 130번 글의 original source empty 축, 134번 글의 partial original source 축과 오늘 line/column 품질 축이 서로 다른 분기라는 점이 분명해진다. 특히 original source code 줄이 일부만 비는 글을 이미 통과했다면, 오늘은 그다음인 line/column 정확도 단계다.

마지막 자료는 local validate 메모 예시다. found/found 이후에는 source map 내부 값과 local line/column 매핑 결과를 같이 남겨야 다음 배포에서 같은 오판을 줄일 수 있다.

sourcesContent와 local column validate 결과를 같이 적는 Sentry 운영 메모 예시다.

이 메모 구조가 있으면 original source empty 분기, source_map_lookup_result not_found 분기와도 경계를 분명히 할 수 있다. 오늘 분기는 경로가 아니라 품질 축이다.

5. 주의사항과 리스크

첫 번째 리스크는 found/found를 곧바로 sourcemap 품질 성공으로 해석하는 것이다. 두 번째 리스크는 sourcesContent가 비어 있는데 column mapping부터 보려는 것이다. 세 번째 리스크는 sourceRoot와 local validate를 한 번에 바꿔 원인을 잃는 것이다.

운영 전에 확인할 때는 최소한 sourcesContent_present, original_source_files_uploaded, sourceRoot, local_line_mapping, local_column_mapping 다섯 칸을 같은 표에 남겨 두는 편이 좋다. 이 다섯 칸이 없으면 line mismatch가 왜 생겼는지 다음 배포에서 다시 설명하기 어렵다.

• found/found는 경로 성공이지 품질 성공이 아니다.
• sourcesContent와 original source files를 먼저 본다.
• column mapping은 local validate까지 내려가서 확인한다.

6. 결론

Sentry에서 source_map_lookup_result가 found인데도 라인 매핑이 틀리다면, 먼저 sourcesContent와 original source files를 확인하고, 그다음 sourceRoot, 마지막에 local column mapping으로 내려가는 편이 맞다. found/found 이후의 문제는 경로보다 품질 축에 가깝기 때문이다. 이 순서를 잡아 두면 prefix나 release를 다시 만지는 불필요한 왕복을 크게 줄일 수 있다.

만약 이 순서를 따라 분기했는데도 마지막에 local validate column mismatch만 남는다면, 이어서 local validate 전용 transform 순서 후속 글을 같이 보면 minifier, transpile, bundle rewrite 중 어디부터 되감아야 할지가 더 짧게 정리된다.

• found/found 뒤에는 payload 품질과 local validate를 본다.
• sourcesContent와 sourceRoot는 서로 다른 단계다.
• column mismatch는 마지막에 local로 확인한다.

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/
4. https://docs.sentry.io/platforms/javascript/guides/connect/sourcemaps/uploading/typescript/