Flutter에서 Cloud Storage 오류 처리

앱을 만들다 보면 예기치 않은 상황으로 인해 오류가 발생하기도 합니다.

의심스러운 경우 함수에서 발생한 예외를 포착하고 오류 메시지 내용을 확인합니다.

final storageRef = FirebaseStorage.instance.ref().child("files/uid");
try {
  final listResult = await storageRef.listAll();
} on FirebaseException catch (e) {
  // Caught an exception from Firebase.
  print("Failed with error '${e.code}': ${e.message}");
}

오류 메시지 처리

오류가 발생하는 이유는 파일이 없는 경우, 사용자에게 파일 액세스 권한이 없는 경우, 사용자가 파일 업로드를 취소한 경우 등 다양합니다.

문제를 정확히 진단하고 오류를 해결하는 데 도움이 되도록 클라이언트에서 발생하는 모든 오류와 발생 원인이 아래에 나와 있습니다.

코드 설명
storage/unknown 알 수 없는 오류가 발생했습니다.
storage/object-not-found 해당 참조에 객체가 없습니다.
storage/bucket-not-found Cloud Storage에 구성된 버킷이 없습니다.
storage/project-not-found Cloud Storage에 구성된 프로젝트가 없습니다.
storage/quota-exceeded Cloud Storage 버킷의 할당량이 초과되었습니다. Spark 요금제를 사용하고 있으면 사용한 만큼만 지불하는 Blaze 요금제로 업그레이드하는 것이 좋습니다. 이미 Blaze 요금제를 사용하고 있으면 Firebase 지원팀에 문의하세요.

중요: 2025년 10월 1일부터 기본 버킷을 포함하여 Cloud Storage를 사용하려면 Blaze 요금제를 사용해야 합니다.
storage/unauthenticated 사용자가 인증되지 않았습니다. 인증한 후 다시 시도해 보세요.
storage/unauthorized 사용자에게 해당 작업을 수행할 수 있는 권한이 없습니다. 보안 규칙이 올바른지 확인해 보세요.
storage/retry-limit-exceeded 작업(업로드, 다운로드, 삭제 등)의 최대 제한 시간이 초과되었습니다. 다시 업로드해 보세요.
storage/invalid-checksum 클라이언트의 파일과 서버에서 수신한 파일의 체크섬이 일치하지 않습니다. 다시 업로드해 보세요.
storage/canceled 사용자가 작업을 취소했습니다.
storage/invalid-event-name 이벤트 이름이 잘못되었습니다. [running, progress, pause] 중 하나여야 합니다.
storage/invalid-url refFromURL()에 제공된 URL이 잘못되었습니다. gs://bucket/object 또는 https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN> 형식이어야 합니다.
storage/invalid-argument put()에 전달되는 인수는 File, Blob 또는 UInt8 배열이어야 합니다. putString()에 전달되는 인수는 원시, Base64 또는 Base64URL 문자열이어야 합니다.
storage/no-default-bucket 구성의 storageBucket 속성에 설정된 버킷이 없습니다.
storage/cannot-slice-blob 로컬 파일이 변경(삭제, 재저장 등)되었을 때 흔히 발생합니다. 파일이 변경되지 않았는지 확인한 후 다시 업로드해 보세요.
storage/server-file-wrong-size 클라이언트의 파일과 서버에서 수신한 파일의 크기가 일치하지 않습니다. 다시 업로드해 보세요.