How to fix storage/unknown: Unknown error occurred in Firebase

Open your browser's Developer Tools (F12 or right-click → Inspect), navigate to the Console tab, and look for expanded error details.

Then switch to the Network tab:
1. Filter by "Fetch/XHR" or search for "firebasestorage"
2. Look for failed requests (shown in red)
3. Click on the failed request
4. Check the Response or Preview tab for detailed error messages

Common detailed messages include:
- "Permission denied" → Storage not enabled
- "IAM permission denied" → Service account issue
- "Bucket does not exist" → Storage bucket not created

The detailed error will point you toward the specific fix needed.

Ensure Storage is properly set up in your Firebase project:

1. Go to the [Firebase Console](https://console.firebase.google.com/)
2. Select your project
3. Navigate to Build → Storage in the left sidebar
4. If you see a "Get Started" button, click it to initialize Storage
5. Choose a security rules mode (test mode for development, locked mode for production)
6. Select a Cloud Storage location (this cannot be changed later)
7. Click "Done"

After enabling Storage, wait 1-2 minutes for the bucket to be fully provisioned before testing your application again.

This is one of the most commonly overlooked causes. The Firebase Storage service account needs proper permissions in Google Cloud Console:

1. Go to [Google Cloud Console IAM](https://console.cloud.google.com/iam-admin/iam)
2. Select the same project as your Firebase app
3. Look for the service account: [email protected]
4. If it doesn't exist or lacks permissions, click "Grant Access"
5. In "New principals", enter:

[email protected]

6. In "Role", select:
- Storage Admin (for full access), or
- Storage Object Admin (for object-level operations only)
7. Click Save

Wait 1-2 minutes for IAM permission changes to propagate, then test your Storage operations again.

Some Firebase projects require upgrading to the Blaze (pay-as-you-go) plan for Storage to work properly:

1. Open the [Firebase Console](https://console.firebase.google.com/)
2. Click the gear icon (⚙️) next to "Project Overview"
3. Select Usage and billing
4. Check your current plan:
- Spark Plan (Free): Limited Storage operations
- Blaze Plan: Pay-as-you-go with generous free tier

If you're on Spark and encountering unknown errors, try upgrading:

1. Click Modify plan
2. Select Blaze
3. Add a billing account
4. Set budget alerts to avoid unexpected charges

Note: The Blaze plan's free tier includes 5 GB storage and 1 GB/day downloads, which is sufficient for most development and small production apps.

Ensure your Firebase app is properly initialized before using Storage:

import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "your-app.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project-id.appspot.com",  // Must be set!
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abcdef"
};

// Initialize Firebase BEFORE using Storage
const app = initializeApp(firebaseConfig);

// Now safe to get Storage instance
const storage = getStorage(app);

Common mistakes:
- Missing or empty storageBucket in config
- Calling getStorage() before initializeApp()
- Using wrong bucket name format

Verify your storageBucket value matches what's shown in Firebase Console → Project Settings → General → Default GCS bucket.

Outdated SDK versions can cause unknown errors due to bugs or API changes. Update all Firebase packages:

# For npm
npm install firebase@latest

# For yarn
yarn add firebase@latest

# Check installed version
npm list firebase

For modular SDK (v9+), ensure you're using the new import syntax:

// Correct (v9+ modular)
import { getStorage, ref, uploadBytes } from "firebase/storage";

const storage = getStorage();
const storageRef = ref(storage, "path/to/file.jpg");
await uploadBytes(storageRef, file);

// Old (v8 compat) - may cause issues
import firebase from "firebase/app";
import "firebase/storage";

const storageRef = firebase.storage().ref();

If you're migrating from v8 to v9+, review the [Firebase upgrade guide](https://firebase.google.com/docs/web/modular-upgrade).

If you're using Firebase Emulators and encountering unknown errors with resumable uploads:

Known issue: uploadBytesResumable() can fail with "storage/unknown" in emulator demo mode. Switch to regular uploadBytes() for testing:

import { getStorage, ref, uploadBytes } from "firebase/storage";

// Instead of uploadBytesResumable
const storage = getStorage();
const fileRef = ref(storage, "test.jpg");

try {
  const snapshot = await uploadBytes(fileRef, file);
  console.log("Upload successful:", snapshot);
} catch (error) {
  console.error("Upload failed:", error.code, error.message);
}

Alternatively, connect to your actual Firebase project instead of emulator for testing uploads.