How to fix storage/invalid-url: Invalid URL format for Cloud Storage reference in Firebase

FirebaseBEGINNERMEDIUMUpdated Dec 29, 2025· 94 views

Firebase Cloud Storage uses the gs:// protocol for references. This error occurs when you use an incorrect URL format (like HTTP URLs) instead of gs://bucket-name/path. Fix it by using the correct reference method.

Quick fix

Fixes INVALID_URL

// firebase-config.js
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  projectId: "your-project-id",
  storageBucket: "your-project-id.appspot.com", // Verify this value
};
  1. Verify your Firebase storage bucket name
  2. Use the correct reference method for your URL type
  3. Ensure the storage bucket is enabled in Firebase
  4. Check for special characters in file paths
firebase — error
// firebase-config.js
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  projectId: "your-project-id",
  storageBucket: "your-project-id.appspot.com", // Verify this value
};
storage/invalid-url: Invalid URL format for Cloud Storage reference

What this error means

Firebase Cloud Storage (powered by Google Cloud Storage) requires references to follow a specific URL format using the gs:// scheme. When you try to create a storage reference with an improperly formatted URL—such as using HTTP/HTTPS URLs, missing the bucket name, or using incorrect syntax—Firebase throws this "Invalid URL format" error. This prevents the SDK from identifying which file or path you want to access.

Typical symptoms

  • Cloud Storage upload or download operations fail immediately
  • Error occurs when calling storage.refFromURL() with an HTTP URL
  • Firebase console shows successful storage configuration, but code fails
  • Other developers report the same error when using your shared config

Common causes

  1. Using HTTP or HTTPS URLs instead of gs:// protocol for refFromURL()
  2. Missing or incorrect bucket name in the storage reference
  3. Malformed path with special characters that aren't URL-encoded
  4. Passing a storage URL from the Firebase console instead of a gs:// URL
  5. Incorrect Firebase config with wrong storageBucket value

How to fix "storage/invalid-url: Invalid URL format for Cloud Storage reference"

1Verify your Firebase storage bucket name

Check your Firebase console to confirm the correct bucket name:
1. Go to Firebase Console > Your Project > Storage
2. Look at the bucket name at the top (format: your-project-id.appspot.com)
3. Verify this matches your storageBucket in your Firebase config

javascript
// firebase-config.js
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  projectId: "your-project-id",
  storageBucket: "your-project-id.appspot.com", // Verify this value
};
2Use the correct reference method for your URL type

Firebase provides different methods for different URL formats:

For gs:// URLs (full storage path):

javascript
import { storage } from './firebase-config';
import { ref } from 'firebase/storage';

// Using refFromURL with gs:// protocol
const fileRef = storage.refFromURL('gs://your-bucket-name/path/to/file.jpg');

For relative paths (preferred):

javascript
import { storage } from './firebase-config';
import { ref } from 'firebase/storage';

// Using ref() with a relative path (simpler and safer)
const fileRef = ref(storage, 'path/to/file.jpg');

For HTTPS download URLs (from console):
If you copy a download URL from the Firebase console (starts with https://), don't use refFromURL(). Instead:
1. Extract the file path from the URL
2. Use ref(storage, 'path/to/file.jpg') instead

3Ensure the storage bucket is enabled in Firebase

Make sure Cloud Storage is properly configured:
1. Go to Firebase Console > Your Project > Build > Storage
2. Click "Get Started" if you haven't created a bucket
3. Select a default location (usually your closest region)
4. Accept the default security rules (they allow authenticated users)
5. Click "Done"

After enabling, your storageBucket value will be auto-populated in your Firebase config. Use this exact value in your code.

4Check for special characters in file paths

If your file path contains special characters, ensure they're properly handled:

javascript
// For files with spaces or special characters, encode them
const fileName = "my file (1).jpg";
const encodedPath = `uploads/${encodeURIComponent(fileName)}`;

const fileRef = ref(storage, encodedPath);

Avoid these issues:
- Spaces should be encoded as %20 or use encodeURIComponent()
- Forward slashes (/) are path separators, not encoded
- Don't include the bucket name in the path when using ref()

5Test the reference with a simple upload or download

Verify your reference works by attempting a simple operation:

javascript
import { storage } from './firebase-config';
import { ref, uploadBytes } from 'firebase/storage';

async function testStorageRef() {
  try {
    const fileRef = ref(storage, 'test/test.txt');
    const blob = new Blob(['test content'], { type: 'text/plain' });

    const snapshot = await uploadBytes(fileRef, blob);
    console.log('Upload successful:', snapshot.ref.fullPath);
  } catch (error) {
    console.error('Storage error:', error.code, error.message);
  }
}

If the error persists, check the browser console for the exact error details which may reveal the specific URL format issue.

Advanced notes

The gs:// URL scheme is specific to Google Cloud Storage and is required by Firebase's SDK. You cannot use HTTP/HTTPS URLs directly with refFromURL(). If you have an HTTPS download URL from the Firebase console, extract the file path and use ref() instead. The error occurs at the SDK level before any network request, so it's purely a validation issue in your code.

Frequently asked questions

What does "INVALID_URL" mean?
Firebase Cloud Storage (powered by Google Cloud Storage) requires references to follow a specific URL format using the gs:// scheme. When you try to create a storage reference with an improperly formatted URL—such as using HTTP/HTTPS URLs, missing the bucket name, or using incorrect syntax—Firebase throws this "Invalid URL format" error. This prevents the SDK from identifying which file or path you want to access.
How do I fix "INVALID_URL"?
Firebase Cloud Storage uses the gs:// protocol for references. This error occurs when you use an incorrect URL format (like HTTP URLs) instead of gs://bucket-name/path. Fix it by using the correct reference method.
What causes "INVALID_URL"?
Using HTTP or HTTPS URLs instead of gs:// protocol for refFromURL() Missing or incorrect bucket name in the storage reference Malformed path with special characters that aren't URL-encoded
Is the "INVALID_URL" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading