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.
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.
Double-check your collection and document ID for typos or case sensitivity issues. Firestore paths are case-sensitive.
// 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 consoleUse the Firebase Console to confirm the collection and document names match exactly.
Use the exists() method to safely check whether a document exists rather than assuming it does.
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.
If using nested collections (e.g., users/{userId}/posts/{postId}), the parent document must exist.
// 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.
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.
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
}Security rules errors can appear similar to NOT_FOUND. Check your rules in the Firebase Console under Firestore Database > Rules.
// 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:
import { enableLogging } from "firebase/firestore";
enableLogging(true);If you see "Permission denied" in logs, it's a security rule issue, not a missing document.
Some NOT_FOUND errors in older SDK versions have been fixed in recent releases.
npm update firebase
# or
npm install firebase@latestAfter updating, clear your node_modules and reinstall:
rm -rf node_modules package-lock.json
npm installIf using React Native or other SDK, update the appropriate package (e.g., react-native-firebase).
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.
messaging/UNSPECIFIED_ERROR: No additional information available
How to fix "messaging/UNSPECIFIED_ERROR: No additional information available" in Firebase Cloud Messaging
App Check: reCAPTCHA Score Too Low
App Check reCAPTCHA Score Too Low
storage/invalid-url: Invalid URL format for Cloud Storage reference
How to fix invalid URL format in Firebase Cloud Storage
auth/missing-uid: User ID identifier required
How to fix "auth/missing-uid: User ID identifier required" in Firebase
auth/invalid-argument: Invalid parameter passed to method
How to fix "auth/invalid-argument: Invalid parameter passed to method" in Firebase