Firebase Storage 'unauthorized' in Flutter? The 5-Step Method to Find the Rule Saying No

By · Published 2026-11-19 · Last verified 2026-11-19

Why does Flutter throw "firebase_storage/unauthorized" when I upload or download?

Because your Cloud Storage Security Rules denied the request. Firebase's Flutter error table describes storage/unauthorized as "User is not authorized to perform the desired action, check your security rules to ensure they are correct." The file, the bucket and your code can all be fine; the rule that matches the path you asked for simply didn't return allow. This guide gives a 5-step method to find the rule that is saying no, the path and wildcard mistakes behind most cases, and the neighbouring errors that look similar but need a different fix. Checked against the Firebase Storage and Security Rules documentation on 2026-11-19.

Grid of the 5-step method for the Firebase Storage unauthorized error in Flutter: print the full path, print the signed-in uid, find the matching rule, replay it in the Rules Playground, change one thing at a time, and never allow read and write to everyone
The 5-step method to find the denying rule.

Which Storage error do you actually have?

Read e.code first, because three codes look alike and have different causes. Firebase's guide to handling Storage errors in Flutter recommends catching the FirebaseException and printing its code and message.

CodeWhat Firebase says it meansWhere to look
unauthorizedNot authorized; check your security rulesThe rule matching that exact path
unauthenticatedUser is unauthenticated; authenticate and try againFirebase Auth sign-in state
object-not-foundNo object exists at the desired referenceThe path or file name in your code
quota-exceededBucket quota exceeded; Cloud Storage for Firebase requires the Blaze planBilling plan and usage
no-default-bucketNo bucket set in the config's storageBucketfirebase_options.dart

Only the first row is a rules problem. If you see object-not-found on a download, the reference points somewhere empty, and changing rules won't help.

The 5-step "find the denying rule" method

This is the order we work through in our own Flutter apps when an upload starts failing:

  1. Print the full path. Log ref.fullPath right before putFile or getDownloadURL. Rules match this string, not what you think the folder is called.
  2. Print the user. Log FirebaseAuth.instance.currentUser?.uid at the same moment. A null user means request.auth is null in your rules.
  3. Find the matching match block. Walk your rules from /b/{bucket}/o down and find the block whose pattern fits that path. If none fits, access is denied.
  4. Replay it in the Rules Playground. In the console's Storage Rules editor, open the Rules Playground and simulate the same operation, path and signed-in uid.
  5. Fix the rule or the path, not both at once. Change one, deploy, and retest, so you know which change worked.
Two columns showing Storage rule paths that match, such as users/{userId}/{file} with users/abc/avatar.jpg and recursive wildcards in rules version 2, against paths that are denied, such as users/abc.jpg and version 1 recursive wildcards
Paths that match the rule, and paths that don't.

Why doesn't my wildcard match the path?

Usually because the path has a different number of segments than the rule. A single wildcard like {userId} matches exactly one path segment, so match /users/{userId}/{fileName} covers users/abc123/avatar.jpg but not users/abc123.jpg and not users/abc123/photos/avatar.jpg.

// Code uploads to: profile_images/abc123.png   (2 segments)
// Rule expects:    profile_images/{userId}/{file} (3 segments)  -> denied

// Option A: change the code
FirebaseStorage.instance
    .ref('profile_images/${user.uid}/avatar.png');

// Option B: change the rule
match /profile_images/{fileName} {
  allow write: if request.auth != null
    && fileName == request.auth.uid + '.png';
}

Recursive wildcards have a version trap too. Firebase's core syntax page says that in rules version 1, {path=**} matches one or more path elements, not zero or more, so /images/{prefix}/{file=**} doesn't match /images/badge.png. Version 2 matches zero or more, and you opt in by putting rules_version = '2'; at the top. The same page notes that the list operation, used by listAll(), only works with version 2.

Is request.auth.uid == userId failing for a signed-in user?

Then check that userId is actually defined by a wildcard in the path. Firebase's Security Rules and Authentication page shows the working shape: match /users/{userId}/{fileName} with allow write: if request.auth != null && request.auth.uid == userId;. If your rule compares against userId but the match pattern is /{allPaths=**}, there is no userId variable and the condition can't pass.

Also confirm the upload uses the same uid. Uploading to users/${someOtherId}/..., for example an ID from your Firestore document rather than the auth uid, fails by design. If Firestore writes in the same screen also fail, the cause is shared; our guide to Firestore permission-denied in Flutter covers the database side.

Can file size or content type cause "unauthorized"?

Yes, if your rules validate them. Firebase's rules-conditions page shows rules such as request.resource.size < 5 * 1024 * 1024 and request.resource.contentType.matches('image/.*'). A 6 MB photo, or a file uploaded with no content type, fails those conditions and comes back as unauthorized, not as a size error.

final meta = SettableMetadata(contentType: 'image/jpeg');
await ref.putFile(file, meta); // set contentType explicitly

Compress or resize images before upload so they pass your size rule. If your app later forwards the same media somewhere else, check that platform's limits as well; AutoX lists media size limits for a Telegram-to-X upload pipeline as one example.

Four boxes of other rule conditions that return unauthorized: a file size limit, a contentType check, App Check enforcement for an unregistered app, and a Firestore lookup without the permission grant
Rules that can also say no.

Could App Check or a Firestore lookup be the reason?

They can, and both are easy to miss. Firebase's App Check documentation says that once you enable enforcement for a product, only registered apps can reach its backend resources, and that requests aren't required to carry valid tokens until enforcement is on. If you turned on enforcement for Storage and a debug build has no registered debug token, test that build before blaming your rules; our guide to staging Firebase App Check in Flutter walks through it.

Storage rules can also call firestore.get() and firestore.exists(). Firebase's rules-conditions page says that when you first save Storage rules that use these functions, the console or CLI prompts you to enable permissions connecting the two products. If that grant is missing, or the document path is wrong, the lookup fails and the request is denied.

How do you stop this coming back?

Keep the rules and the code paths in one place you review together. Write the storage paths your app uses as constants, keep a comment in the rules file naming each one, and deploy rules with an explicit project, for example firebase deploy --only storage --project your-project-id, so a staging rule set never lands on production by accident. If a callable returns UNAUTHENTICATED instead of a Storage rule denial, see the 5-step method for a Firebase callable UNAUTHENTICATED error in Flutter.

We review rules on a schedule; our security rules review cadence applies the same way to Storage. For context on what GSPTeck builds with Flutter and Firebase, see GSPTeck's apps and services.

Vertical Pinterest graphic with five checks for the Firebase Storage unauthorized error in Flutter
Pinterest pin: storage/unauthorized in Flutter.

FAQ

Should I set Storage rules to allow read, write: if true to fix it?

No. That makes every file in the bucket readable and writable by anyone. Firebase strongly recommends restricting access for production apps; fix the path or condition instead.

Why does the upload work in the Rules Playground but not in the app?

The simulation used different inputs. Compare the logged ref.fullPath, the signed-in uid and the content type from the app with what you typed into the Playground.

What is the difference between unauthorized and unauthenticated?

Unauthenticated means no signed-in user reached Storage. Unauthorized means a request arrived and your rules said no. Sign-in fixes the first; only a rule or path change fixes the second.

Do Storage rules changes take effect immediately?

Deploy the rules and retest with a fresh request. If a test still fails, check that you deployed to the project the app is actually configured for.

Sources