[Sentry][프론트엔드] Source Map Debug API에서 source_file_lookup_result가 not_found이고 scraping status도 실패할 때 frame URL prefix와 artifact bundle을 어느 순서로 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] Source Map Debug API에서 source_file_lookup_result가 not_found이고 scraping status도 실패할 때 frame URL prefix와 artifact bundle을 어느 순서로 다시 보나

Sentry sourcemap 문제를 보다 보면 Source Map Debug API에서 source_file_lookup_result=not_found가 보이는데 scraping status 실패까지 같이 붙는 경우가 있다. 2026년 7월 16일 기준 Sentry 공식 문서를 다시 보면 frame abs_path, Debug ID 기본 흐름, sourceMappingURL 기반 public fetch, legacy upload 이름 체계가 각각 다른 레이어를 설명한다. 이 글은 두 실패가 동시에 보일 때 frame URL prefix와 artifact bundle을 어떤 순서로 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 source_file_lookup_result=not_found와 scraping 실패가 같이 보이면 artifact bundle부터 확인하기보다 frame URL prefix를 먼저 봐야 한다. Source Map Debug API는 abs_path를 같이 돌려주므로 runtime frame 이름이 upload 이름 체계와 맞는지 먼저 자를 수 있다.

그다음 단계가 sourceMappingURL과 public fetch다. frame 이름이 이미 틀린 상태에서 scraping만 재시도하면 lookup 레이어와 공개 fetch 레이어를 섞어 읽게 된다.

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

실무에서 흔한 실패는 세 가지다. 첫째, artifact bundle이 있는지만 보고 frame 이름 체계는 맞을 것이라고 본다. 둘째, scraping status가 실패했으니 공개 map 파일만 다시 열어 본다. 셋째, Debug ID 기본 경로와 legacy release 업로드 경로가 섞였는데 어느 쪽이 현재 주 경로인지 정하지 않는다.

Sentry 문서는 Source Map Debug API에 frame abs_path와 lookup 결과를 같이 보여 준다. 또 sourcemaps overview는 Debug ID가 기본 연결 방식이라고 설명하고, hosting publicly와 legacy uploading methods 문서는 sourceMappingURL과 URL prefix 해석을 다룬다. 즉 lookup 실패와 scraping 실패는 서로 다른 층위다.

• 증상: source_file_lookup_result는 not_found인데 artifact bundle은 있어 보인다.
• 실패: scraping만 재시도하고 frame URL prefix는 안 본다.
• 막힘: Debug ID 경로와 legacy upload 경로를 동시에 믿는다.
• 누락: abs_path, sourceMappingURL, upload prefix를 한 로그에 안 적는다.

신호	먼저 볼 층위	의미
source_file_lookup_result=not_found	frame URL prefix	이름 체계 mismatch 가능성
scraping status 실패	sourceMappingURL / public fetch	공개 map fetch 실패 가능성
둘 다 동시에 실패	frame URL prefix 먼저	lookup 레이어가 선행이다

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

실무 순서는 네 단계면 충분하다. 먼저 Source Map Debug API의 abs_path와 source_file_lookup_result를 읽어 runtime frame 이름을 복원한다. 두 번째로 upload prefix와 rewriteFrames 같은 canonicalization 경로를 붙인다. 세 번째로 sourceMappingURL과 공개 URL 응답을 따로 확인한다. 마지막으로 그 뒤에야 artifact bundle과 legacy upload 흔적을 다시 비교한다. 이때 응답 필드를 복사하고, 로그를 저장하고, URL을 확인하고, prefix 값을 비교하고, 재시도 순서를 메모해 두면 같은 오류를 더 짧게 재현할 수 있다.

1. abs_path와 source_file_lookup_result로 frame 이름부터 복원한다.
2. upload prefix와 rewriteFrames를 비교해 canonical 이름을 맞춘다.
3. sourceMappingURL과 public fetch 실패를 별도 로그로 본다.
4. 그다음 artifact bundle과 legacy upload 흔적을 재확인한다.

source-map triage memo

abs_path=https://cdn.example.com/static/js/main.abc123.js
upload_prefix=~/static/js
rewrite_frames=app:/// disabled
source_mapping_url=main.abc123.js.map
public_map_fetch=failed
artifact_bundle_present=true

핵심은 업로드가 있었는지보다 먼저 Sentry가 어떤 이름으로 파일을 찾고 있었는지 보는 것이다. 이름 체계가 틀린 상태에서 scraping만 고치면 진단 순서가 계속 꼬인다.

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

첫 자료는 Source Map Debug API 응답 필드다. 이번 증상은 source file lookup이 not_found라는 점과 scraping 실패가 함께 보일 때부터 출발한다.

Source Map Debug API는 frame별 source_file_lookup_result를 따로 보여 주므로 frame URL 레이어와 업로드 레이어를 분리해서 읽을 수 있다.

즉 이 상태는 단순히 source map이 없다는 한 줄보다 더 구체적이다. 먼저 frame이 어떤 canonical 이름으로 찾히는지부터 봐야 한다.

두 번째 자료는 같은 API 예시 안의 abs_path 필드다. frame URL prefix 문제는 release artifact 존재 여부보다 먼저 이 값을 읽어야 보인다.

Source Map Debug API 예시는 release_process 안에 abs_path와 release 정보를 같이 보여 준다.

그래서 not_found가 보이면 먼저 runtime frame URL과 upload prefix가 같은 이름 체계를 쓰는지부터 분리해야 한다. artifact bundle 존재만 보면 방향을 헷갈리기 쉽다.

세 번째 자료는 Sentry JavaScript sourcemaps overview다. 현재 기본 흐름은 Debug ID를 build output에 주입해 연결하는 경로다.

Sentry sourcemaps overview는 기본 연결 방식이 Debug ID 주입 기반이라고 설명한다.

따라서 legacy release 업로드 관성으로 문제를 보면 source_file not_found를 잘못 해석할 수 있다. 지금 프로젝트가 어떤 경로를 우선 쓰는지 먼저 정해야 한다.

네 번째 자료는 hosting publicly 문서다. Sentry는 sourceMappingURL을 따라 HTTP 요청으로 map 파일을 가져오려는 경로도 설명한다.

Hosting publicly 문서는 sourceMappingURL을 기준으로 source map URL을 해석하고 HTTP fetch를 시도하는 흐름을 설명한다.

즉 scraping 실패가 같이 보이면 upload artifact 문제와 public fetch 문제를 나눠 읽어야 한다. 둘은 같은 실패처럼 보여도 조치 순서가 다르다.

다섯 번째 자료는 legacy uploading methods 문서다. 이 문서는 sourceMappingURL comment와 업로드 이름, url prefix 관계를 다시 보여 준다.

Legacy uploading methods 문서는 sourceMappingURL comment가 브라우저와 Sentry가 map 위치를 찾는 기준이 된다고 설명한다.

그래서 frame URL prefix와 artifact bundle을 비교하기 전에 마지막 줄 주석과 실제 업로드 이름을 다시 붙여 보는 절차가 필요하다.

실무에서는 lookup 실패와 scraping 실패를 한 표에 놓고 분리해야 한다. frame 이름 mismatch와 public fetch 실패는 로그가 비슷해도 처리 순서가 다르다.

source_file_lookup_result not_found와 scraping 실패가 함께 보일 때의 분기표다.

이미 release_has_some_artifact=false 경로 글와 Debug ID와 release 업로드 혼합 글이 업로드 레이어를 다뤘다면, 이번 표는 frame URL prefix와 public scraping을 같이 읽는 다음 단계다.

마지막 자료는 운영 메모 예시다. frame URL과 sourceMappingURL, 업로드 prefix를 같은 로그에 남겨야 다음 디버깅이 짧아진다.

Source Map Debug API 상태와 frame URL prefix를 같이 메모하는 운영 예시다.

이런 순서로 적어 두면 상태 조합 결정표 글에서 더 세부 분기로 곧바로 들어갈 수 있다.

5. 주의사항과 리스크

가장 큰 리스크는 scraping 실패를 봤다고 해서 모든 원인을 공개 map 파일 문제로 몰아가는 것이다. frame URL prefix mismatch가 먼저면 public fetch를 아무리 고쳐도 source file lookup은 계속 실패한다.

또 Debug ID 기본 흐름과 legacy upload 흔적을 동시에 믿는 것도 위험하다. 현재 프로젝트가 어느 경로를 우선 사용하는지부터 정해야 필드 해석이 짧아진다.

• 주의: source_file_lookup_result not_found는 frame 이름 체계부터 보라는 신호다.
• 주의: scraping 실패는 lookup 실패와 같은 층위가 아니다.
• 주의: abs_path, sourceMappingURL, upload prefix를 한 로그에 남겨야 한다.

6. 결론

Source Map Debug API에서 source_file_lookup_result가 not_found이고 scraping status도 실패할 때는 frame URL prefix를 먼저 맞추고, 그다음 sourceMappingURL 기반 public fetch와 artifact bundle을 분리해 읽는 편이 맞다. 이 순서를 지켜야 lookup 레이어와 공개 fetch 레이어를 덜 섞는다.

관련 흐름으로는 상태 조합 결정표 글, release artifact 경로 글, Debug ID와 legacy upload 혼합 글을 같이 보면 Sentry sourcemap 분기표가 더 촘촘해진다.

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/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
4. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/
5. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/hosting-publicly/