Firebase Crashlytics에서 UUID Missing 해결 방법 (iOS / Swift)

Firebase Crashlytics에서 UUID Missing 해결 방법 (iOS / Swift)

iOS 앱을 운영하면서 Firebase Crashlytics를 사용하다 보면 다음과 같은 메시지를 콘솔에서 볼 수 있다.

Missing dSYM
Upload missing dSYM files to process crashes

또는 특정 UUID가 누락되었다는 메시지가 표시될 수도 있다. 이 경우 Crashlytics에서 크래시 로그를 정상적으로 해석하지 못하기 때문에 스택 트레이스가 메모리 주소 형태로만 표시된다.

이 글에서는 Firebase Crashlytics에서 발생하는 UUID Missing 문제의 원인과 해결 방법을 정리한다.

UUID Missing 오류란 무엇인가

Crashlytics는 앱에서 발생한 크래시 로그를 사람이 읽을 수 있는 형태로 변환하기 위해 dSYM(Debug Symbol File)을 사용한다.

dSYM 파일에는 앱 바이너리의 UUID 정보가 포함되어 있으며, Crashlytics는 이 UUID를 기준으로 크래시 로그를 매칭한다.

만약 Firebase 서버에 업로드된 dSYM의 UUID와 앱의 UUID가 다르면 다음과 같은 문제가 발생한다.

• 함수명이 표시되지 않음
• 메모리 주소만 표시됨
• 크래시 원인 분석 어려움

UUID Missing이 발생하는 주요 원인

1. dSYM 파일이 업로드되지 않은 경우

가장 흔한 원인은 Crashlytics에 dSYM 파일이 업로드되지 않은 경우다. 특히 Swift Package Manager로 Firebase를 설치한 프로젝트에서 Run Script 설정이 누락되는 경우가 많다.

2. 다른 빌드의 dSYM 업로드

Archive 빌드와 다른 UUID의 dSYM을 업로드하면 Crashlytics에서 매칭이 되지 않는다.

3. Archive 대신 Debug 빌드 사용

Crashlytics는 보통 Release 또는 Archive 빌드 기준으로 분석된다. Debug 빌드의 dSYM을 업로드하면 UUID mismatch가 발생할 수 있다.

4. Xcode Build Phase Run Script 누락

Crashlytics는 빌드 과정에서 dSYM을 자동 업로드하도록 Run Script를 사용한다. 이 스크립트가 누락되면 dSYM이 Firebase로 전달되지 않는다.

dSYM UUID 확인 방법

먼저 로컬에서 dSYM UUID를 확인해야 한다.

dwarfdump --uuid MyApp.app.dSYM

출력 결과는 다음과 비슷하다.

UUID: 12345678-ABCD-1234-ABCD-1234567890AB (arm64) MyApp.app.dSYM

이 UUID 값이 Firebase Crashlytics 콘솔에서 요구하는 UUID와 동일해야 한다.

dSYM 위치 찾기

Archive 빌드를 하면 dSYM은 다음 위치에 생성된다.

Xcode Organizer
→ Archives
→ Show in Finder
→ Products
→ dSYMs

여기서 해당 앱의 dSYM 파일을 찾을 수 있다.

Crashlytics에 dSYM 수동 업로드

자동 업로드가 되지 않는 경우 Firebase CLI를 사용해 수동 업로드할 수 있다.

firebase crashlytics:symbols:upload \
--app=YOUR_FIREBASE_APP_ID \
PATH_TO_DSYM

업로드 후 몇 분이 지나면 Crashlytics에서 정상적으로 스택 트레이스가 표시된다.

Xcode Run Script 확인

Crashlytics 자동 업로드를 위해 Build Phases에 다음 스크립트가 있어야 한다.

"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"

이 스크립트가 없다면 Archive 시 dSYM 업로드가 수행되지 않는다.

SPM 환경에서 자주 발생하는 문제

Swift Package Manager로 Firebase를 설치한 경우 다음 문제가 발생할 수 있다.

• Run Script 경로 변경
• dSYM 자동 업로드 실패
• Archive 빌드에서 스크립트 실행 안됨

이 경우 Run Script 경로를 다시 설정하면 해결되는 경우가 많다.

UUID Missing 문제 해결 체크리스트

• dSYM 파일 생성 여부 확인
• dSYM UUID 확인
• Firebase 콘솔 UUID 확인
• Run Script 설정 확인
• Archive 빌드 기준 업로드
• 필요 시 수동 업로드

마무리

Firebase Crashlytics에서 UUID Missing 문제가 발생하면 대부분 dSYM 업로드 문제로 인해 발생한다.

특히 Swift Package Manager 환경에서는 Run Script 경로 문제로 자동 업로드가 실패하는 경우가 많기 때문에 Archive 빌드 기준으로 dSYM 생성과 업로드 여부를 확인하는 것이 중요하다.

이 과정을 점검하면 대부분의 UUID Missing 문제를 해결할 수 있다.

Firebase Crashlytics 관련 글

• Firebase Crashlytics SPM 설치 방법 (Swift / iOS)
• Firebase Crashlytics 설정 방법 (Swift / iOS)
• Firebase Crashlytics 크래시 로그 확인하는 방법 (Swift / iOS)
• Firebase Crashlytics dSYM Missing 오류 해결 방법 (SPM 환경 포함)
• Firebase Crashlytics에서 UUID Missing 해결 방법 (iOS / Swift)