How to Troubleshoot Common FlutterFlow Database Problems

A permission-denied error means Firestore's security rules are blocking the read or write operation. The most common causes are: (1) test mode rules expired (30-day expiry), (2) rules require authentication but the user is not logged in, (3) rules check a field name that doesn't match your actual Firestore field, (4) rules check resource.data on a create operation instead of request.resource.data. To diagnose: go to Firebase Console → Firestore Database → Rules → click Rules Playground. Set the operation to your failing operation (get/list/create), enter the document path, set authentication to match your user's state, and click Run. The playground shows exactly which rule line caused the denial. Fix the rule, click Publish, and test again within 1 minute.

If your Backend Query returns zero results but you can see data in Firebase Console, the issue is almost always: (1) field name mismatch — Firestore field names are case-sensitive (userId vs UserId), (2) filter value mismatch — filtering by a DocumentReference but passing a String ID, (3) wrong collection path — extra slash, wrong subcollection path, (4) filter operator mismatch — using == on an array field instead of arrayContains. In FlutterFlow, open the Backend Query that returns empty results. Check the Collection/Group field for typos. Check each Filter condition — click on the filter value and confirm the field name exactly matches what you see in Firebase Console (copy-paste from the console to be sure). For DocumentReference filters, ensure you are passing a DocumentReference variable, not a String ID.

When you filter by one field and order by a different field (or filter by two different fields), Firestore requires a composite index. Without it, the query fails with: FAILED_PRECONDITION: The query requires an index. You can create it here: [URL]. In FlutterFlow's Run Mode console output, look for this error message and the URL embedded in it. Clicking the URL opens Firebase Console with the index pre-filled — click Create Index. Alternatively, go to Firebase Console → Firestore Database → Indexes → Composite → Add Index. Enter the collection name, add the two fields with their sort directions (Ascending or Descending), and click Create. Index building takes 2-10 minutes. Your query will work automatically once the index status shows Enabled.

Firestore real-time listeners push updates to your app automatically when data changes. If changes in Firebase Console do not appear in your FlutterFlow app within a few seconds, the Backend Query is configured as a single-time query instead of a real-time listener. In FlutterFlow, click on the page or widget containing the Backend Query. Open the Backend Query settings. Look for the Single Time Query toggle — if it is ON, the query fetches data once on load and never again. Toggle it OFF to enable real-time listening. Note: real-time queries hold a WebSocket connection for the lifetime of the page. Only enable real-time on queries where live updates are genuinely needed (chat messages, live scores, collaborative lists). For static content (product descriptions, user profile), Single Time Query ON is correct and more efficient.

Firestore documents have a 1MB maximum size. If a write fails with Document exceeds maximum size or The document has an invalid key, your data is too large for a single document. Common causes: storing messages, order items, or activity logs as arrays inside a document instead of a subcollection; storing large text content (article body, HTML); or uploading binary data directly to Firestore instead of Firebase Storage. Fix by moving growing data to subcollections: instead of posts/{id}.comments (array), create posts/{id}/comments/{commentId} as individual documents. For large text or binary data, upload to Firebase Storage and store only the download URL in Firestore.

Firestore enables offline persistence by default on mobile — your app caches data locally and serves it from cache while fetching fresh data from the server. If users see stale data that does not update even after a while, common causes are: (1) no network connection and cache is stale, (2) app was force-closed while pending writes were queued, (3) real-time listener was stopped and not restarted. For most cases, the fix is to add a Pull to Refresh action: in FlutterFlow, on your ListView or page, add a Refresh Indicator widget. In its On Refresh action, re-execute the Backend Query. This forces a fresh fetch from Firestore. For persistent stale cache issues, add a Custom Action that calls FirebaseFirestore.instance.clearPersistence() during app initialization — note this clears all locally cached data.