Backend Issues: Typo errors fixed, improved formatting, assets added

docs/troubleshooting/backend-issues/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Backend"
+}

docs/troubleshooting/backend-issues/listview_gray_box_and_red_screen_errors.md

@@ -0,0 +1,81 @@
+---
+keywords: ['database', 'listview', 'mode']
+slug: /listview-gray-box-and-red-screen-errors
+title: ListView Gray Box and Red Screen Errors
+---
+
+# ListView Gray Box and Red Screen Errors
+
+When loading a list of items from the database, you might encounter a gray box or red error screen. This article explains the possible causes and how to resolve them.
+
+:::info[Prerequisites]
+- Ensure your query is correctly connected to a Firestore collection or CMS.
+- Confirm that your app builds and runs correctly in **Run** and **Test** modes.
+:::
+
+**Understanding the Error:**
+
+A **gray box** usually indicates that the backend query failed to return results. A **red screen** in Test mode suggests a runtime error caused by invalid data or query failure.
+
+**Step-by-Step Troubleshooting:**
+
+1. **Verify Query Results**
+
+    - If the query is successful and returns items, the list will populate as expected.
+    - If there are no records matching the query, you will see the **empty state** you configured.
+    - If the query fails, a gray box (in Run mode) or a red error screen (in Test mode) will appear.
+
+    ![Empty State](../assets/20250430121239249713.png)
+
+    :::tip
+    Always configure an empty state for lists. This helps distinguish between a failed query and an empty dataset.
+    :::
+
+2. **Behavior by Mode**
+
+    - **Run mode**: Displays a gray box when the query fails.
+    - **Test mode**: Shows a red screen with a specific error message.
+
+        **Example: Working Query with No Results**  
+        ![Working Query](../assets/20250430121239492027.png)
+
+        **Example: Failed Query**  
+        ![Failed Query](../assets/20250430121239708989.png)
+
+3. **Check for Null Values in the Data**
+
+    Null values in critical fields may cause queries or widgets to fail.
+
+    Here is how to check for null values:
+
+        1. Inspect your data in **Firebase** or **CMS** for any fields with `null` values.
+        2. Pay attention to fields used in filters, formatting, or conditional visibility.
+        3. For example, if `created_time` is null and you are formatting a date from this field, the query may fail.
+
+        **Example: Null Field Causing Error**
+
+        ![Null Field Example](../assets/20250430121240227391.png)  
+        ![Date Formatting Error](../assets/20250430121240508011.png)
+
+    :::note
+    Use **visibility rules** to hide widgets that depend on potentially null values.
+    :::
+
+4. **Handle Document-From-Reference Queries Safely**
+
+    If you use document references inside a list item widget, and the reference is null or missing, it will break the query.
+
+    ![Broken Reference Example](../assets/20250430121240818334.png)
+
+    :::note
+    Always add a visibility rule to any widget performing document-from-reference queries. This ensures the widget is only visible when the reference is valid.
+    :::
+
+
+:::info[Summary]
+- A **gray box** means the backend query failed.
+- A **red screen** indicates a runtime error in **Test mode**.
+- **Null values** in your database are a common cause of failure.
+- Always configure **empty states** and apply **visibility rules** to handle null or missing data gracefully.
+:::
+

docs/troubleshooting/backend-issues/listview_returning_only_one_item.md

@@ -0,0 +1,35 @@
+---
+keywords: ['listview', 'returning', 'only']
+slug: /listview-returning-only-one-item
+title: ListView Returning Only One Item
+---
+# Fix ListView Only Returning One Item
+
+If your **ListView** is only showing one item, this guide will walk you through the common reasons and how to resolve the issue.
+
+:::info[Prerequisites]
+- A working Firebase or CMS integration.
+- A dynamic layout widget such as `ListView`, `GridView`, or `Column`.
+- At least two documents in your Firestore collection for testing.
+:::
+
+Follow the steps below to resolve the issue:
+
+1. **Use a Dynamic Widget**  
+   Make sure you're using a widget like `ListView`, `GridView`, or `Column` that supports dynamic content.
+
+2. **Confirm the Query Type**  
+   Ensure the query is set to return a **list of documents**, not a single document.
+
+3. **Review Applied Filters**  
+   If you are using filters, check that multiple records in your database satisfy those filter conditions.
+
+4. **Check Firestore Data**  
+   Open your Firestore collection and verify that it contains **multiple records**.
+
+5. **Verify List Type Fields**  
+   If querying a single field, confirm it's defined as a **List** in both Firebase and FlutterFlow.
+
+:::tip
+To test your setup, remove all filters temporarily and use a basic list query. This helps isolate whether the issue is with filtering or the query type.
+:::

docs/troubleshooting/backend-issues/resolving_firebase_configuration_issues.md

@@ -0,0 +1,71 @@
+---
+keywords: ['firebase', 'issues', 'configuration']
+slug: /resolving-firebase-configuration-issues
+title: Resolving Firebase Configuration Issues
+---
+# Resolving Firebase Configuration Issues
+
+If you're experiencing backend errors, failed schema validation, or data sync issues, this guide will help you verify and fix your Firebase setup in FlutterFlow.
+
+:::info[Prerequisites]
+- You must have already connected your Firebase project to FlutterFlow.
+- You should have access to your Firebase console with admin rights.
+:::
+
+Follow the steps below to fix firebase configuration:
+
+1. **Grant Required Permissions**
+
+   Assign the following permissions to `[email protected]` in your Firebase project:
+    - Editor  
+    - Cloud Functions Admin  
+    - Service Account User
+
+    Learn how to **[assign Firebase permissions](/integrations/firebase/connect-to-firebase/#allow-flutterflow-to-access-your-project)**.
+
+2. **Update Firestore Rules**
+
+   Update your Firestore security rules to allow access for FlutterFlow.
+
+   After making changes:
+        - Remove `[email protected]` from your authenticated users.
+        - Redeploy your Firestore rules.
+        - Validate your schema again.
+
+        ![](../assets/20250430121532523511.png)
+
+3. **Match Field Types and Names**
+
+   Check that data field types and names match between Firestore and FlutterFlow exactly. Mismatches will cause query errors.
+
+4. **Validate Firestore Schema in FlutterFlow**
+
+   Use the **Validate** button under **Firestore → Settings** in FlutterFlow to confirm that your collection schema matches your Firestore structure.
+
+   ![](../assets/20250430121532793176.png)
+
+5. **Reset Firebase Setup (If Needed)**
+
+   If issues persist after following the steps above:
+        - Revoke the current setup.
+        - Reconnect your Firebase project using the **[Firebase setup instructions](/integrations/firebase/connect-to-firebase/)**.
+
+6. **Add Authorized Domains**
+
+   In the Firebase console, go to **Authentication → Sign-in Method → Authorized Domains** and add: `app.flutterflow.io`
+
+7. **Refresh FlutterFlow**
+
+    Make sure you're using the latest version of the platform:
+
+        - Press `Ctrl`/`Cmd + Shift + R`
+        - Clear your browser cache
+        - Log out and back in to FlutterFlow
+
+8. **Upgrade to Blaze Plan (If Using Cloud Functions)**
+
+    Cloud Functions such as Push Notifications and Payments require a billing-enabled Firebase project. Make sure you’re on the **Blaze Plan**.
+
+:::tip
+After updating Firestore rules, always validate the schema using the **Validate** button before proceeding with other fixes.
+:::

docs/troubleshooting/backend-issues/update_document_action_fails_during_backend_call.md

@@ -0,0 +1,58 @@
+---
+keywords: ['call', 'document', 'backend']
+slug: /update-document-action-fails-during-backend-call
+title: Update Document Action Fails During Backend Call
+---
+# Update Document Action Fails During Backend Call
+
+When performing the **Update Document** action, you may encounter a situation where the loading indicator appears but then stops without completing the action. This indicates that the update was unsuccessful. If the update succeeds, the next steps in your action flow, such as displaying an alert dialog, should execute automatically.
+
+![](../assets/20250430121241690449.gif)
+
+![](../assets/20250430121241899370.png)
+
+:::note
+After performing the update action, always verify that the data has been correctly updated in your database. If your document is not streamed in real-time within your app, the updated data may not immediately appear. Check the data in FlutterFlow CMS or directly in Firebase to confirm the update.
+:::
+
+**Causes of Document Update Failures:**
+
+When the update action fails, the action flow stops, preventing any subsequent actions from executing.
+
+There are two common reasons why the update action may fail:
+
+- **Permission Issue in Firestore**
+
+    The user may not have the necessary permission to write to the document.
+
+    ![](../assets/20250430121242149430.png)
+
+    **Cause:**  
+    The Firestore security rules may not allow the current user to write (edit) documents. 
+
+    **Solution:**  
+    Review and configure your Firestore rules to grant write permission. For example, allowing write access to authenticated users is often sufficient if your app requires user authentication.
+
+- **Data Type Mismatch**
+
+    The values you are attempting to write may not match the expected field types.
+
+    For example, assigning a string value to a field that expects an integer will result in failure.
+
+    ![](../assets/20250430121242530889.png)
+
+    **Cause:**  
+    Attempting to write a value of the wrong type, such as assigning text to a number field.
+
+    **Solution:**  
+    Verify that the values being written match the expected data types for each field. If the data comes from an API call or form input, consider using custom actions to convert the value to the appropriate type before performing the update.
+
+    :::note 
+    If you want to save a text field value as a number, ensure that the text field input type is set to **Number**.
+    :::
+
+:::info[Additional Troubleshooting]
+You can check for error details in your browser's developer console (F12). For example, permission errors will typically appear in the console logs, as shown below:
+
+![](../assets/20250430121242814005.png)
+:::