This error occurs when Firebase Storage cannot locate the Cloud Storage bucket configured in your Firebase app, typically due to a missing, deleted, or incorrectly specified bucket name. It prevents all file upload and download operations.
The "storage/bucket-not-found" error indicates that Firebase is unable to find the Cloud Storage bucket that your app is trying to access. Unlike the "no-default-bucket" error which occurs when the storageBucket property is completely missing from your Firebase configuration, this error happens when the property is set but points to a bucket that does not exist, has been deleted, or is not accessible to your Firebase project. Firebase Storage is built on Google Cloud Storage, and each Firebase project automatically gets a default bucket (usually named "project-id.firebasestorage.app" or "project-id.appspot.com"). When Firebase cannot locate or authenticate to this bucket, all storage operations are blocked. This error acts as a safety mechanism to prevent your code from attempting operations on non-existent storage locations.
Visit [Firebase Console](https://console.firebase.google.com/) and select your project. Look for Storage in the left navigation menu. If you do not see it or see a "Get Started" button, Cloud Storage has not been enabled.
Click Get Started to begin the setup process:
1. Choose your security rules:
- Test mode: Allows all reads and writes (suitable for development only)
- Production mode: Denies all reads and writes until rules are configured
2. Select your storage location (cannot be changed later):
- us-central1 (Iowa) - Standard choice for US-based projects
- europe-west1 (Belgium) - For GDPR compliance and EU data residency
- asia-northeast1 (Tokyo) - For Asian region latency
3. Click Done and wait for Firebase to provision your bucket (typically 10-30 seconds).
Once Storage is enabled, navigate to the Storage section in Firebase Console. Your bucket name appears at the top of the Files tab.
Important: Bucket naming changed in October 2024:
- New projects (Oct 2024+): Format is your-project-id.firebasestorage.app
- Older projects: Format is your-project-id.appspot.com
Copy your exact bucket name from the console. The name will NOT include the gs:// protocol prefix. You can verify the bucket name in multiple places:
- Storage page in Firebase Console
- Project Settings → Storage location and bucket name
- Google Cloud Console → Cloud Storage buckets
Update your code to use the exact bucket name from the Firebase Console. Do NOT include gs:// or any extra characters:
// 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", // Exact bucket name, no gs://
messagingSenderId: "123456789",
appId: "YOUR_APP_ID"
};
const app = initializeApp(firebaseConfig);
const storage = getStorage(app);// Admin SDK (Node.js/TypeScript)
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();Critical: Ensure:
- No spaces before or after the bucket name
- No extra quotes or escaped characters
- No gs:// protocol prefix in initialization (only use full URL if using refFromURL())
If you are uncertain about your bucket name or configuration, download a fresh config from Firebase Console:
1. Go to Project Settings (gear icon) → General
2. Scroll to Your apps section
3. Find your web or mobile app, or click Add app if none exists
4. Copy the firebaseConfig object from the code snippet (Web SDK)
5. Replace your entire configuration object with the downloaded one
For environment variables, store the bucket name separately:
# .env.local
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app// firebase-config.js
const firebaseConfig = {
apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID
};After updating environment variables, restart your development server or redeploy your application.
Verify that your bucket is now accessible with a simple test function:
import { getStorage, ref, listAll } from "firebase/storage";
async function testStorageConnection() {
try {
const storage = getStorage();
const listRef = ref(storage, "/");
const result = await listAll(listRef);
console.log("✓ Storage bucket found and accessible!");
console.log("Bucket name:", storage.app.options.storageBucket);
console.log("Folders:", result.prefixes.length);
console.log("Files:", result.items.length);
return true;
} catch (error) {
if (error.code === "storage/bucket-not-found") {
console.error("✗ Bucket not found. Verify bucket name and permissions.");
} else {
console.error("Error:", error.code, error.message);
}
return false;
}
}
// Run test on app load
testStorageConnection();If successful, you should see confirmation in the console that the bucket is accessible. This confirms your configuration is correct.
For custom buckets beyond the default, you must create them in Google Cloud Console and explicitly reference them:
// Admin SDK - reference a custom bucket
import * as admin from "firebase-admin";
const customBucket = admin.storage().bucket("gs://my-custom-bucket");Managing multiple environments: In projects with separate development, staging, and production Firebase projects, configure the correct bucket per environment:
const firebaseConfig = {
// ... other config
storageBucket: process.env.NODE_ENV === "production"
? "prod-project.firebasestorage.app"
: "dev-project.firebasestorage.app"
};IAM and permissions: When using Admin SDK with custom service accounts, ensure the service account has storage permissions:
1. Go to Google Cloud Console → IAM & Admin → Service Accounts
2. Select your service account
3. Grant the Storage Object Admin or Storage Admin role
4. The service account needs storage.buckets.get and storage.objects.* permissions
Bucket URL format changes: Firebase changed default bucket naming in October 2024. If you see .firebasestorage.app buckets in your console but old .appspot.com references in your code, re-download your Firebase configuration files. Some projects need updated config files to migrate to the new format (see [react-native-firebase issue #8123](https://github.com/invertase/react-native-firebase/issues/8123)).
Deleted bucket recovery: If you deleted your default bucket in Google Cloud Console, you cannot immediately recreate a bucket with the same name. Either create a new bucket with a different name and update all references, or contact Firebase Support for recovery options. Always test configuration changes in a development environment before deploying to production.
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