How to fix UNKNOWN: An unknown error occurred in Firebase

Open your browser's Developer Tools (F12 or Ctrl+Shift+I on Windows/Linux, Cmd+Option+I on Mac), navigate to the Console tab, and examine the full error object.

Expand the error message to see:
- error.code: The specific error code (may reveal more detail than "UNKNOWN")
- error.message: Full error message text
- error.serverResponse: Server's response payload (if available)
- error.customData: Additional context Firebase provides

Then check the Network tab:
1. Filter by "Fetch/XHR" requests
2. Look for failed requests to firebaseio.com, firebasestorage.googleapis.com, identitytoolkit.googleapis.com, or similar
3. Click the failed request and check:
- Response tab for error details
- Status code (400 = client error, 500 = server error)
- Request Headers to verify authentication headers are present

The detailed message in Network response often reveals the true cause (permission denied, quota exceeded, service unavailable).

Unknown errors can result from Firebase service degradation or outages:

1. Visit the [Firebase Status Dashboard](https://status.firebase.google.com)
2. Check for:
- Green checkmarks: All services operational
- Yellow/orange indicators: Ongoing incident or degradation
- Red indicators: Active outage
3. Look specifically for your service (Authentication, Firestore, Cloud Functions, Cloud Storage, Realtime Database, etc.)
4. If an incident is listed, wait for Firebase to resolve it (usually 5-30 minutes)
5. Subscribe to status updates to get notified of future incidents

If Firebase services are operational, the issue is likely in your application configuration or network connectivity.

The most common cause of UNKNOWN errors is using Firebase services before they're initialized. Verify your initialization order:

// CORRECT: Initialize Firebase first
import { initializeApp } from "firebase/app";
import { getAuth, signInWithEmailAndPassword } from "firebase/auth";
import { getFirestore, getDoc, doc } from "firebase/firestore";

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

// Initialize FIRST
const app = initializeApp(firebaseConfig);

// Get service references AFTER initialization
const auth = getAuth(app);
const db = getFirestore(app);

// NOW safe to use services
await signInWithEmailAndPassword(auth, email, password);
const docSnap = await getDoc(doc(db, "users", "user-id"));

// INCORRECT: Using services before initialization
const auth = getAuth(); // No app initialized yet!
await signInWithEmailAndPassword(auth, email, password); // UNKNOWN error!

Ensure your initialization code runs at application startup, before any service calls.

Stale cached data or corrupted local storage can cause UNKNOWN errors:

1. Clear IndexedDB and LocalStorage:
- Open DevTools → Application tab
- Expand Storage → Local Storage and delete all firebase entries
- Expand Storage → IndexedDB and delete all firebase-related databases
- Close and reopen the application

2. Hard refresh browser cache:
- Windows/Linux: Ctrl+Shift+Delete
- Mac: Cmd+Shift+Delete
- Select "All time" and click "Clear data"

3. For React Native:

import AsyncStorage from '@react-native-async-storage/async-storage';
   
   // Clear Firebase stored tokens
   await AsyncStorage.removeItem('@firebase:token');
   await AsyncStorage.removeItem('@firebase:auth');

4. For Flutter:

import 'package:firebase_core/firebase_core.dart';
   
   // Force sign out to clear cached credentials
   await FirebaseAuth.instance.signOut();

After clearing cache, the application will download fresh configuration and authentication tokens.

Each Firebase service must be explicitly enabled in the Firebase Console:

1. Go to your [Firebase Console](https://console.firebase.google.com/)
2. Select your project
3. For each service you're using, enable it:
- Authentication: Build → Authentication → Sign-in method
- Firestore: Build → Firestore Database → Create database
- Cloud Storage: Build → Storage → Get started
- Cloud Functions: Build → Functions → Get started
- Realtime Database: Build → Realtime Database → Create database

4. If you see "Get started" or "Create database" buttons, click them to initialize
5. Wait 1-2 minutes for services to be fully provisioned
6. Restart your application

Services may show as enabled in the console but not be fully initialized. The provisioning process takes time, so waiting a minute or two before retrying often resolves UNKNOWN errors.

Outdated Firebase SDKs can have bugs or compatibility issues causing UNKNOWN errors:

For web projects:

npm install firebase@latest

For React:

npm install firebase@latest
npm install react-firebase-hooks@latest

For Node.js/Backend:

npm install firebase-admin@latest

For React Native:

npm install @react-native-firebase/app@latest @react-native-firebase/auth@latest @react-native-firebase/firestore@latest

For Flutter:

flutter pub upgrade firebase_core firebase_auth firebase_cloud_firestore

For Android (gradle):
Update build.gradle to latest Firebase BOM version:

dependencies {
  implementation platform('com.google.firebase:firebase-bom:33.1.0') // Use latest version
  implementation 'com.google.firebase:firebase-auth'
  implementation 'com.google.firebase:firebase-firestore'
}

After updating, rebuild your application. Many UNKNOWN errors are fixed in newer SDK versions.

Network issues and browser extensions frequently cause UNKNOWN errors:

Test network connectivity:

// Check internet connection before Firebase operations
if (!navigator.onLine) {
  console.error("No internet connection");
  // Retry when online
  window.addEventListener('online', retryFirebaseOperation);
  return;
}

Disable browser extensions temporarily:
1. Open DevTools → More tools → Deactivate extensions (or use incognito mode)
2. Reload the page and test your application
3. If the error disappears, one of your extensions is blocking Firebase:
- Ad blockers (Ublock Origin, Adblock Plus)
- CORS extensions
- Privacy tools (Privacy Badger, Ghostery)
- VPN extensions
4. Add your application domain to the extension's whitelist, or disable the extension for your site

Check firewall/proxy:
- Verify your corporate firewall isn't blocking *.googleapis.com or *.firebasestorage.com
- If behind a corporate proxy, configure SDK to route through proxy if supported
- Test with a mobile hotspot to bypass corporate network

Network connectivity issues are often invisible in console logs, so they're easy to overlook.

Stale or invalid authentication tokens can cause UNKNOWN errors when Firebase attempts operations:

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth();

// Monitor authentication state changes
onAuthStateChanged(auth, async (user) => {
  if (user) {
    // User is signed in
    const token = await user.getIdToken(true); // Force refresh
    console.log("Valid auth token obtained");
    
    // Now safe to use Firebase services
  } else {
    // User is signed out
    console.log("User not authenticated");
  }
});

// For long-running operations, refresh token periodically
async function firebaseOperationWithTokenRefresh(operation) {
  const user = auth.currentUser;
  if (!user) throw new Error("User not authenticated");
  
  try {
    // Refresh token before operation
    await user.getIdToken(true);
    return await operation();
  } catch (error) {
    if (error.code === "auth/network-request-failed" || error.message.includes("unknown")) {
      // Retry with fresh token
      await user.getIdToken(true);
      return await operation();
    }
    throw error;
  }
}

For service accounts (backend):

const admin = require("firebase-admin");

// Ensure service account JSON is valid and has correct permissions
const serviceAccount = require("./service-account-key.json");

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: "https://your-project.firebaseio.com"
});

// Service account tokens auto-refresh, but verify permissions
const auth = admin.auth();
const db = admin.firestore();