This error occurs when Firebase Storage cannot find or access the specified bucket, typically because Cloud Storage has not been enabled in the Firebase Console or the bucket name in your configuration is incorrect or missing.
The "storage/bucket-not-found" error indicates that Firebase Storage is trying to access a Cloud Storage bucket that either does not exist, has not been created, or is not accessible by your Firebase project. Unlike the "no-default-bucket" error which occurs when the storageBucket property is completely missing, this error typically happens when the property is set but points to an invalid, deleted, or inaccessible bucket. Firebase Storage is built on top of Google Cloud Storage, and each Firebase project can have one or more storage buckets. When you reference a bucket that Firebase cannot locate or authenticate against, this error is thrown. This is Firebase's way of preventing operations on non-existent storage locations. The error commonly occurs in projects where Cloud Storage was never enabled through the Firebase Console, where developers are migrating between Firebase projects, or when attempting to use custom bucket names that haven't been properly provisioned.
Navigate to the [Firebase Console](https://console.firebase.google.com/), select your project, and click on Storage in the left navigation menu. If you see a "Get Started" button, this means Cloud Storage has not been enabled yet.
Click Get Started, choose your security rules option:
- Test mode: Allows all reads and writes (only for development)
- Production mode: Denies all reads and writes until you configure rules
Select your preferred storage location (this cannot be changed later). Common choices:
- us-central1 (Iowa) - Default for most US projects
- europe-west1 (Belgium) - For EU data residency
- asia-northeast1 (Tokyo) - For Asian traffic
Click Done and wait for Firebase to provision your default bucket. This usually takes 10-30 seconds.
Once Storage is enabled, you should see your bucket name displayed at the top of the Storage page in the Firebase Console.
The bucket name format depends on when your project was created:
- New projects (Oct 2024+): your-project-id.firebasestorage.app
- Older projects: your-project-id.appspot.com
Click on the bucket name to copy it to your clipboard. Make sure to copy the exact name without the gs:// prefix.
Update your Firebase initialization code to use the exact bucket name from the console:
// Web SDK (modular v9+)
import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";
const firebaseConfig = {
apiKey: "YOUR_API_KEY",
authDomain: "your-project.firebaseapp.com",
projectId: "your-project",
storageBucket: "your-project.firebasestorage.app", // Use exact bucket name
messagingSenderId: "123456789",
appId: "YOUR_APP_ID"
};
const app = initializeApp(firebaseConfig);
const storage = getStorage(app);// Admin SDK (Node.js)
import * as admin from 'firebase-admin';
admin.initializeApp({
credential: admin.credential.applicationDefault(),
storageBucket: 'your-project.firebasestorage.app' // No gs:// prefix
});
const bucket = admin.storage().bucket();Important: Ensure there are no extra spaces, quotes, or the gs:// protocol prefix in your bucket name.
If your project is older or if you're uncertain about the correct configuration, download a fresh config from Firebase Console:
1. Go to Project Settings (gear icon) → General
2. Scroll to "Your apps" section
3. Select your web app or click "Add app" if none exists
4. Copy the firebaseConfig object from the code snippet
5. Update your .env file or configuration:
# .env.local
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app// config.js
const firebaseConfig = {
// ... other config
storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET
};Restart your development server or redeploy after updating environment variables.
Verify the bucket is accessible with a simple test:
import { getStorage, ref, listAll } from "firebase/storage";
async function testStorage() {
try {
const storage = getStorage();
const listRef = ref(storage, '/');
const result = await listAll(listRef);
console.log('✓ Storage bucket found and accessible');
console.log('Bucket:', storage.app.options.storageBucket);
} catch (error) {
if (error.code === 'storage/bucket-not-found') {
console.error('✗ Bucket still not found. Check configuration.');
} else {
console.error('Error:', error.code, error.message);
}
}
}
testStorage();If successful, you should see confirmation that the bucket is accessible.
For projects using custom buckets beyond the default, you must explicitly create them in Google Cloud Console:
// Admin SDK - create a custom bucket programmatically
import * as admin from 'firebase-admin';
const bucket = admin.storage().bucket('gs://my-custom-bucket');
// Note: The bucket must exist in GCP first, or use:
const { Storage } = require('@google-cloud/storage');
const storage = new Storage();
await storage.createBucket('my-custom-bucket', {
location: 'us-central1',
storageClass: 'STANDARD'
});Multi-project configurations: If you're working with multiple Firebase projects (e.g., development, staging, production), ensure each environment uses its own bucket:
const firebaseConfig = {
storageBucket: process.env.NODE_ENV === 'production'
? 'prod-project.firebasestorage.app'
: 'dev-project.firebasestorage.app'
};IAM Permissions: When using Firebase Admin SDK with custom service accounts, ensure the service account has the storage.buckets.get permission. In Google Cloud Console → IAM, verify your service account has the Storage Object Admin or Storage Admin role.
Migrating from old to new bucket URLs: If you're seeing a .firebasestorage.app bucket in your console but your code uses .appspot.com, you may need to re-download your Firebase config files. Firebase changed default bucket naming in October 2024, and some projects need updated config files to use the new format. See [react-native-firebase issue #8123](https://github.com/invertase/react-native-firebase/issues/8123) for details on this migration scenario.
Bucket deletion: If you accidentally deleted your default bucket in Google Cloud Console, you cannot recreate it with the same name immediately. Contact Firebase Support or create a new bucket and update all configurations to reference it.
Callable Functions: INTERNAL - Unhandled exception
How to fix "Callable Functions: INTERNAL - Unhandled exception" in Firebase
auth/invalid-hash-algorithm: Hash algorithm doesn't match supported options
How to fix "auth/invalid-hash-algorithm: Hash algorithm doesn't match supported options" in Firebase
Hosting: CORS configuration not set up properly
How to fix CORS configuration in Firebase Hosting
auth/reserved-claims: Custom claims use reserved OIDC claim names
How to fix "reserved claims" error when setting custom claims in Firebase
Callable Functions: UNAUTHENTICATED - Invalid credentials
How to fix "UNAUTHENTICATED - Invalid credentials" in Firebase Callable Functions