Handle errors for Cloud Storage on Flutter

If you have an*.appspot.com default bucket, your Firebase project must be upgraded to thepay-as-you-go Blaze pricing plan byFebruary 03, 2026 to maintain access to your default bucket.Learn more.

Sometimes when you're building an app, things don't go as planned and anerror occurs!

When in doubt, catch the exception thrown by the functionand see what the error message has to say.

finalstorageRef=FirebaseStorage.instance.ref().child("files/uid");try{finallistResult=awaitstorageRef.listAll();}onFirebaseExceptioncatch(e){// Caught an exception from Firebase.print("Failed with error '${e.code}':${e.message}");}
Note: By default, aCloud Storage for Firebase bucket requiresFirebase Authenticationto perform any action on the bucket's data or files. You can change yourFirebase Security Rules forCloud Storage toallow unauthenticated access for specific situations.However, for most situations, we strongly recommendrestricting access and setting up robust security rules(especially for production apps). Note that if you useGoogleApp Engine and have a defaultCloud Storage bucket with a nameformat of*.appspot.com, you may need to considerhow your security rules impact access toApp Engine files.

Handle Error Messages

There are a number of reasons why errors may occur, including the filenot existing, the user not having permission to access the desired file, or theuser cancelling the file upload.

To properly diagnose the issue and handle the error, here is a full list ofall the errors our client will raise, and how they occurred.

CodeDescription
storage/unknownAn unknown error occurred.
storage/object-not-foundNo object exists at the desired reference.
storage/bucket-not-foundNo bucket is configured for Cloud Storage
storage/project-not-foundNo project is configured for Cloud Storage
storage/quota-exceededQuota on yourCloud Storage bucket has been exceeded. If you're on the Spark pricing plan, consider upgrading to thepay-as-you-go Blaze pricing plan. If you're already on the Blaze pricing plan, reach out to Firebase Support.

Important: StartingFebruary 03, 2026, theBlaze pricing plan will berequired to useCloud Storage, even default buckets.
storage/unauthenticatedUser is unauthenticated, please authenticate and try again.
storage/unauthorizedUser is not authorized to perform the desired action, check your security rules to ensure they are correct.
storage/retry-limit-exceededThe maximum time limit on an operation (upload, download, delete, etc.) has been excceded. Try uploading again.
storage/invalid-checksumFile on the client does not match the checksum of the file received by the server. Try uploading again.
storage/canceledUser canceled the operation.
storage/invalid-event-nameInvalid event name provided. Must be one of [running,progress,pause]
storage/invalid-urlInvalid URL provided torefFromURL(). Must be of the form:gs://bucket/object orhttps://firebasestorage.googleapis.com/v0/b/bucket/o/object?token=<TOKEN>
storage/invalid-argumentThe argument passed toput() must beFile,Blob, orUInt8 Array. The argument passed toputString() must be a raw,Base64, orBase64URL string.
storage/no-default-bucketNo bucket has been set in your config'sstorageBucket property.
storage/cannot-slice-blobCommonly occurs when the local file has changed (deleted, saved again, etc.). Try uploading again after verifying that the file hasn't changed.
storage/server-file-wrong-sizeFile on the client does not match the size of the file received by the server. Try uploading again.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-03 UTC.