Android에서 Cloud Storage 오류 처리
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
예기치 않은 상황으로 인해 오류가 발생하기도 합니다.
의심스러운 경우 반환되는 오류를 점검하여 오류 메시지의 내용을 확인하세요.
다음 코드에서는 Cloud Storage가 반환하는 오류 코드와 오류 메시지를 검사하는 커스텀 오류 핸들러 구현을 보여줍니다. 이러한 오류 핸들러는 Cloud Storage API에서 사용하는 다양한 객체(예: UploadTask, FileDownloadTask)에 추가할 수 있습니다.
Kotlin
internal inner class MyFailureListener : OnFailureListener {
override fun onFailure(exception: Exception) {
val errorCode = (exception as StorageException).errorCode
val errorMessage = exception.message
// test the errorCode and errorMessage, and handle accordingly
}
}
Java
class MyFailureListener implements OnFailureListener {
@Override
public void onFailure(@NonNull Exception exception) {
int errorCode = ((StorageException) exception).getErrorCode();
String errorMessage = exception.getMessage();
// test the errorCode and errorMessage, and handle accordingly
}
}
오류 메시지를 확인했고 Cloud Storage Security Rules가 작업을 허용하는데도 오류가 해결되지 않는 경우 지원 페이지를 방문하여 문의해 주시기 바랍니다.
오류 메시지 처리
오류가 발생하는 이유는 파일이 없는 경우, 사용자에게 파일 액세스 권한이 없는 경우, 사용자가 파일 업로드를 취소한 경우 등 다양합니다.
문제를 정확히 진단하고 오류를 해결하는 데 도움이 되도록 클라이언트에서
발생하는 모든 오류와 발생 원인을 아래와 같이 제공해 드립니다. 이 표에 나와 있는 오류 코드는 StorageException 클래스에 정수 상수로 정의되어 있습니다.
| 코드 |
이유 |
ERROR_UNKNOWN |
알 수 없는 오류가 발생했습니다. |
ERROR_OBJECT_NOT_FOUND |
지정된 참조에 객체가 없습니다. |
ERROR_BUCKET_NOT_FOUND |
Cloud Storage를 위해 구성된 버킷이 없습니다. |
ERROR_PROJECT_NOT_FOUND |
Cloud Storage를 위해 구성된 프로젝트가 없습니다. |
ERROR_QUOTA_EXCEEDED |
Cloud Storage 버킷의 할당량이 초과되었습니다. Spark 요금제를 사용하고 있으면 사용한 만큼만 지불하는 Blaze 요금제로 업그레이드하는 것이 좋습니다. 이미 Blaze 요금제를 사용하고 있으면 Firebase 지원팀에 문의하세요.
중요: 2025년 10월 1일부터 기본 버킷을 포함하여 Cloud Storage를 사용하려면 Blaze 요금제를 사용해야 합니다. |
ERROR_NOT_AUTHENTICATED |
사용자가 인증되지 않았습니다. 인증한 후 다시 시도해 보세요. |
ERROR_NOT_AUTHORIZED |
사용자에게 요청한 작업을 할 수 있는 권한이 없습니다. 규칙이 올바른지 확인해 보세요. |
ERROR_RETRY_LIMIT_EXCEEDED |
작업(업로드, 다운로드, 삭제 등)의 최대 제한 시간이 초과되었습니다. 다시 시도하세요. |
ERROR_INVALID_CHECKSUM |
클라이언트의 파일과 서버에서 수신한 파일의 체크섬이 일치하지 않습니다. 다시 업로드해 보세요. |
ERROR_CANCELED |
사용자가 작업을 취소했습니다. |
또한 잘못된 URL로 getReferenceFromUrl()을 호출하려고 하면 IllegalArgumentException이 발생합니다. 위 메서드의 인수는 gs://bucket/object 또는 https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN> 형식이어야 합니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-22(UTC)
[null,null,["최종 업데이트: 2025-08-22(UTC)"],[],[],null,["\u003cbr /\u003e\n\nSometimes things don't go as planned and an error occurs.\n\nWhen in doubt, check the error returned and see what the error message says.\nThe following code shows a custom error handler implementation that inspects\nthe error code and error message returned by Cloud Storage. Such error\nhandlers can be added to various objects used in the Cloud Storage API (for\nexample, `UploadTask` and `FileDownloadTask`). \n\nKotlin \n\n```kotlin\ninternal inner class MyFailureListener : OnFailureListener {\n override fun onFailure(exception: Exception) {\n val errorCode = (exception as StorageException).errorCode\n val errorMessage = exception.message\n // test the errorCode and errorMessage, and handle accordingly\n }\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/kotlin/StorageActivity.kt#L492-L498\n```\n\nJava \n\n```java\nclass MyFailureListener implements OnFailureListener {\n @Override\n public void onFailure(@NonNull Exception exception) {\n int errorCode = ((StorageException) exception).getErrorCode();\n String errorMessage = exception.getMessage();\n // test the errorCode and errorMessage, and handle accordingly\n }\n}https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/storage/app/src/main/java/com/google/firebase/referencecode/storage/StorageActivity.java#L618-L625\n```\n\nIf you've checked the error message and have Cloud Storage Security Rules that allow your\naction, but are still struggling to fix the error, visit our\n[Support page](/support) and let us know how we can help.\n\nHandle Error Messages\n\nThere are a number of reasons why errors may occur, including the file\nnot existing, the user not having permission to access the desired file, or the\nuser cancelling the file upload.\n\nTo properly diagnose the issue and handle the error, here is a full list of all\nthe errors our client will raise, and how they can occur. Error codes in this\ntable are defined in the `StorageException` class as integer constants.\n\n| Code | Reason |\n|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `ERROR_UNKNOWN` | An unknown error occurred. |\n| `ERROR_OBJECT_NOT_FOUND` | No object exists at the specified reference. |\n| `ERROR_BUCKET_NOT_FOUND` | No bucket is configured for Cloud Storage |\n| `ERROR_PROJECT_NOT_FOUND` | No project is configured for Cloud Storage |\n| `ERROR_QUOTA_EXCEEDED` | Quota on your Cloud Storage bucket has been exceeded. If you're on the Spark pricing plan, consider upgrading to the [pay-as-you-go Blaze pricing plan](/pricing). If you're already on the Blaze pricing plan, reach out to Firebase Support. **Important** : Starting October 1, 2025, the [Blaze pricing plan will be *required* to use Cloud Storage](/docs/storage/faqs-storage-changes-announced-sept-2024), even default buckets. |\n| `ERROR_NOT_AUTHENTICATED` | User is unauthenticated, please authenticate and try again. |\n| `ERROR_NOT_AUTHORIZED` | User is not authorized to perform the requested action, check your rules to ensure they are correct. |\n| `ERROR_RETRY_LIMIT_EXCEEDED` | The maximum time limit on an operation (upload, download, delete, etc.) has been excceded. Try again. |\n| `ERROR_INVALID_CHECKSUM` | File on the client does not match the checksum of the file received by the server. Try uploading again. |\n| `ERROR_CANCELED` | User canceled the operation. |\n\nAdditionally, attempting to call `getReferenceFromUrl()` with an invalid URL\nwill result in an `IllegalArgumentException` from being thrown. The argument to\nthe above method must be of the form `gs://bucket/object` or\n`https://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=\u003cTOKEN\u003e`"]]
