Firebase 실무 오류 해결 모음: Storage, Firestore, Auth 체크리스트

학습 목표와 사전 지식

목표: Firebase 오류를 제품·요청·권한 주체로 분류하고 알맞은 해결 글로 이동합니다.
사전 지식: Firebase Auth·Firestore·Storage 기본 역할, SDK error.code

먼저 어느 요청이 실패했는지 고정하세요. “Firebase가 안 된다”를 코드 한 조각으로 해결하려 하면 서로 다른 제품의 설정을 바꾸게 됩니다. 아래 표에서 실패한 제품과 코드를 고르고 해당 요청만 재현합니다.

증상	첫 비교 대상	학습 글 ID
auth/unauthorized-domain	실제 호스트·Auth 승인 도메인·projectId	4493
Firestore permission-denied	인증 주체·문서 경로·Rules·쿼리	3003
Unsupported field value: undefined	쓰기 payload 직렬화	9293
Storage 403/404	bucket·fullPath·token/SDK 요청 구분	3074
브라우저 CORS	Origin·메서드·preflight 응답	3409
인덱스 삭제 질문	원격 정의·배포 파일·살아 있는 쿼리	1441

오류 기록은 민감값 없이

기록할 항목은 발생 시각, 제품, error.code, 호출 작업(get/list/create 등), 개발/운영 구분, 로그인 역할, 경로 패턴입니다. 실제 ID token, 비밀번호, 서비스 계정 키, 다운로드 token URL을 붙이지 않습니다. 경로도 개인정보가 포함되면 가상의 ID로 바꿔 재현 자료를 만듭니다.

Auth 성공 뒤 DB 실패를 분리하기

Google 로그인은 됐지만 Firestore 쿼리가 거부됐다면 승인 도메인이 아니라 문서 권한을 봅니다. 예를 들어 ownerId == A인 문서만 읽도록 한 규칙에서 전체 컬렉션을 요청하면 데이터가 적어도 실패할 수 있습니다. Admin SDK에서 같은 읽기가 성공해도 클라이언트 Rules가 맞다는 증거는 아닙니다.

CORS 문구 뒤 실제 오류를 찾기

Storage의 Network 응답과 SDK error.code를 함께 봅니다. 없는 bucket, 객체 없음, 인증 거부, 사용량 문제를 먼저 분리하고 실제 Origin과 CORS 응답이 맞는지 확인합니다. 새 탭으로 token URL이 열려도 인증 SDK 읽기와 같은 권한 경로는 아닙니다. CORS 목록을 바꾸어도 Rules는 바뀌지 않습니다.

변경은 하나씩, 검증은 허용과 거부를 함께

원본 코드·규칙·설정을 보관하고 개발 프로젝트에서 같은 요청을 재현합니다. 한 원인에 대응하는 파일이나 설정을 수정한 다음 원래 요청을 반복합니다. 정상 사용자 성공만 확인하지 말고 다른 사용자·비로그인 거부도 확인하세요. 배포 성공 메시지는 API 성공, 화면 정상, 실제 색인 상태와 다른 결과입니다.

다음 조사로 넘기는 기준

오류 코드가 바뀌면 새 코드와 시점을 기록합니다. 재현이 안 되면 네트워크·세션·배포 버전·캐시 조건 차이를 확인하고 해결됐다고 확정하지 않습니다. Functions 이벤트 오류는 로그의 이벤트 ID·재전달·리전을 함께 보고, 웹 UI 문제는 초기 로딩과 비동기 상태 경쟁을 별도 확인합니다.

직접 확인할 결과

오류별 실제 내부 글 ID/URL 매핑
민감 정보 없는 재현 기록 양식
개별 실제 장애 재현 미실행

검증 범위와 기준일

공식 문서 확인일: 2026-09-13. 웹 SDK 예제는 모듈형 API 기준입니다. 이 글의 코드·구조 정적 검토와 실제 클라우드 인증·저장·배포 검증을 구분합니다. 본인 개발 Firebase 프로젝트의 실제 인증·권한·배포 요청은 이 편집 환경에서 실행하지 않았습니다.

이어서 학습하기

• Firebase 실무 로드맵: Auth, Firestore, Storage, Functions
• Firebase 초기화 구조: Next.js firebase.ts 설계 기준
• Firebase Authentication 사용 기준: 로그인 유지와 비밀번호 재설정
• Firebase 보안 규칙 설계: Firestore와 Storage 권한 관리하기
• Firestore CRUD 사용법: 컬렉션 구조와 읽기 쓰기 흐름
• Firebase Auth Context 설계: 로그인 권한과 라우팅 관리하기
• Firebase Storage 이미지 업로드 사용법: 상품 이미지 관리 흐름 만들기
• Firebase Custom Claims 사용법: 관리자 권한 구분하기
• Firebase Functions v2 사용법: 트리거 배포 Secret 처리
• Firestore seed data 설계: 리뷰 더미 데이터 구조 잡기
• Firebase 배포 제외 파일 설정: firebase.json의 ignore 사용법
• Firebase Firestore 인덱스 삭제 질문 해결: 배포 중 안전하게 판단하기
• Firebase Auth unauthorized-domain 오류 해결: 로그인 도메인 설정 확인
• Firebase permission-denied 오류 해결: Firestore Rules 체크리스트
• Firebase Storage 이미지 오류 해결: 403·404·token·Rules 확인법
• Firebase CORS 오류 해결: Storage 이미지 업로드가 막힐 때 확인할 설정
• Firestore undefined 오류 해결: 선택 필드가 저장을 막을 때

공식 문서

• https://firebase.google.com/docs/storage/web/handle-errors
• https://firebase.google.com/docs/firestore/security/rules-query
• https://firebase.google.com/docs/auth/web/google-signin
• https://firebase.google.com/docs/functions/firestore-events