How to fix NOT_FOUND: The specified document does not exist in Firebase

FirebaseBEGINNERMEDIUMUpdated Dec 22, 2025· 143 views

This error occurs when your code tries to fetch a Firestore document that doesn't exist at the specified path. The fix depends on whether the document should exist or whether you need to handle missing documents gracefully.

Quick fix

Fixes NOT_FOUND

// Wrong - "users" and "userId" are case-sensitive
const docRef = doc(db, "Users", userId);

// Correct - ensure exact collection and document names
const docRef = doc(db, "users", userId);
console.log(docRef.path); // Verify path in console
  1. Verify the document path is correct
  2. Check if the document exists before accessing it
  3. Ensure parent documents exist for nested collections
  4. Wrap getDoc calls in try-catch for error handling
firebase — error
// Wrong - "users" and "userId" are case-sensitive
const docRef = doc(db, "Users", userId);
// Correct - ensure exact collection and document names
const docRef = doc(db, "users", userId);
console.log(docRef.path); // Verify path in console
NOT_FOUND: The specified document does not exist

What this error means

The NOT_FOUND error is raised by Firebase Firestore when your application attempts to retrieve, update, or listen to a document at a path where no document currently exists. This can happen for several reasons: the document path is incorrect, the document was deleted, the parent document for a nested collection was never created, or you're connecting to the wrong Firestore database instance. Unlike some databases that throw exceptions immediately, Firestore's getDoc() method returns a DocumentSnapshot with an exists property that you should check.

Typical symptoms

  • Application crashes with "NOT_FOUND: The specified document does not exist" when calling getDoc() or get()
  • Firestore console shows the document exists, but your code receives a NOT_FOUND error
  • Batch update operations fail on a single document with "No document to update" error
  • Real-time listeners initialized but immediately return NOT_FOUND for document paths
  • API requests return gRPC Error 5 (NOT_FOUND) with no additional context

Common causes

  1. Document path is incorrect - typos in collection name or document ID (Firestore is case-sensitive)
  2. Document was deleted - the document existed but has since been removed from the database
  3. Document was never created - trying to fetch a document that was never written in the first place
  4. Parent document doesn't exist - when using nested collections, Firestore doesn't auto-create parent documents
  5. Wrong Firestore database instance - connected to wrong project or using a named database instead of default
  6. Document exists but you lack read permissions - security rules deny access despite document existing
  7. Race condition - document was deleted between the time you checked for it and attempted to access it

How to fix "NOT_FOUND: The specified document does not exist"

1Verify the document path is correct

Double-check your collection and document ID for typos or case sensitivity issues. Firestore paths are case-sensitive.

javascript
// Wrong - "users" and "userId" are case-sensitive
const docRef = doc(db, "Users", userId);

// Correct - ensure exact collection and document names
const docRef = doc(db, "users", userId);
console.log(docRef.path); // Verify path in console

Use the Firebase Console to confirm the collection and document names match exactly.

2Check if the document exists before accessing it

Use the exists() method to safely check whether a document exists rather than assuming it does.

javascript
import { doc, getDoc } from "firebase/firestore";

const docRef = doc(db, "users", userId);
const docSnap = await getDoc(docRef);

if (docSnap.exists()) {
  console.log("Document data:", docSnap.data());
} else {
  console.log("No document found - handle gracefully");
  // Return null, show error to user, or create document
}

This is the safest pattern and prevents NOT_FOUND errors from crashing your application.

3Ensure parent documents exist for nested collections

If using nested collections (e.g., users/{userId}/posts/{postId}), the parent document must exist.

javascript
// First, create the parent document
await setDoc(doc(db, "users", userId), {
  email: userEmail,
  createdAt: new Date(),
});

// Then create the nested document
await setDoc(doc(db, "users", userId, "posts", postId), {
  title: "My Post",
  content: "Content here",
});

In the Firestore Console, parent documents without data appear in italics. If a parent is italicized, create it explicitly with setDoc before writing subcollections.

4Wrap getDoc calls in try-catch for error handling

When using getDocFromCache() (reading from local cache), a NOT_FOUND error is thrown if no cached copy exists. Use try-catch to handle this scenario.

javascript
import { doc, getDocFromCache } from "firebase/firestore";

const docRef = doc(db, "users", userId);

try {
  const docSnap = await getDocFromCache(docRef);
  if (docSnap.exists()) {
    console.log("Cached document:", docSnap.data());
  }
} catch (error) {
  console.log("Document not in cache - fetch from server instead");
  const docSnap = await getDoc(docRef);
  // Handle as normal with exists() check
}
5Verify Firestore security rules allow read access

Security rules errors can appear similar to NOT_FOUND. Check your rules in the Firebase Console under Firestore Database > Rules.

javascript
// Overly restrictive rule that might appear as NOT_FOUND
allow read: if request.auth != null;

// More explicit error message (add to your rules)
allow read: if request.auth != null else deny;

Enable Firestore Debug logging to see the actual error:

javascript
import { enableLogging } from "firebase/firestore";
enableLogging(true);

If you see "Permission denied" in logs, it's a security rule issue, not a missing document.

6Update Firebase SDK to latest version

Some NOT_FOUND errors in older SDK versions have been fixed in recent releases.

bash
npm update firebase
# or
npm install firebase@latest

After updating, clear your node_modules and reinstall:

bash
rm -rf node_modules package-lock.json
npm install

If using React Native or other SDK, update the appropriate package (e.g., react-native-firebase).

Advanced notes

Some users report NOT_FOUND errors when documents definitely exist in the console. This can happen with gRPC connection issues or database routing problems. Try: (1) Invalidating browser cache and deleting IndexedDB (DevTools > Application > Clear Storage), (2) Using a different network to rule out ISP/proxy issues, (3) Checking if you're using a named database instead of the default with db(config, "[database-name]"), (4) Verifying your connection to the correct Firebase project with console.log(firebase.app().options.projectId). For batch write operations that fail on individual documents, consider using writeBatch with error handling to log which specific documents are causing NOT_FOUND errors.

Frequently asked questions

What does "NOT_FOUND" mean?
The NOT_FOUND error is raised by Firebase Firestore when your application attempts to retrieve, update, or listen to a document at a path where no document currently exists. This can happen for several reasons: the document path is incorrect, the document was deleted, the parent document for a nested collection was never created, or you're connecting to the wrong Firestore database instance. Unlike some databases that throw exceptions immediately, Firestore's getDoc() method returns a DocumentSnapshot with an exists property that you should check.
How do I fix "NOT_FOUND"?
This error occurs when your code tries to fetch a Firestore document that doesn't exist at the specified path. The fix depends on whether the document should exist or whether you need to handle missing documents gracefully.
What causes "NOT_FOUND"?
Document path is incorrect - typos in collection name or document ID (Firestore is case-sensitive) Document was deleted - the document existed but has since been removed from the database Document was never created - trying to fetch a document that was never written in the first place
Is the "NOT_FOUND" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading