diff --git a/docs/troubleshooting/assets/20250430121239249713.png b/docs/troubleshooting/assets/20250430121239249713.png new file mode 100644 index 00000000..4f3d7b71 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121239249713.png differ diff --git a/docs/troubleshooting/assets/20250430121239492027.png b/docs/troubleshooting/assets/20250430121239492027.png new file mode 100644 index 00000000..5cd0efd9 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121239492027.png differ diff --git a/docs/troubleshooting/assets/20250430121239708989.png b/docs/troubleshooting/assets/20250430121239708989.png new file mode 100644 index 00000000..a8fd874f Binary files /dev/null and b/docs/troubleshooting/assets/20250430121239708989.png differ diff --git a/docs/troubleshooting/assets/20250430121239967301.png b/docs/troubleshooting/assets/20250430121239967301.png new file mode 100644 index 00000000..23289996 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121239967301.png differ diff --git a/docs/troubleshooting/assets/20250430121240227391.png b/docs/troubleshooting/assets/20250430121240227391.png new file mode 100644 index 00000000..4baa9bc1 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121240227391.png differ diff --git a/docs/troubleshooting/assets/20250430121240508011.png b/docs/troubleshooting/assets/20250430121240508011.png new file mode 100644 index 00000000..751a8660 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121240508011.png differ diff --git a/docs/troubleshooting/assets/20250430121240818334.png b/docs/troubleshooting/assets/20250430121240818334.png new file mode 100644 index 00000000..7307d463 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121240818334.png differ diff --git a/docs/troubleshooting/assets/20250430121241416661.png b/docs/troubleshooting/assets/20250430121241416661.png new file mode 100644 index 00000000..58c3e224 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121241416661.png differ diff --git a/docs/troubleshooting/assets/20250430121241690449.gif b/docs/troubleshooting/assets/20250430121241690449.gif new file mode 100644 index 00000000..f3a3a78b Binary files /dev/null and b/docs/troubleshooting/assets/20250430121241690449.gif differ diff --git a/docs/troubleshooting/assets/20250430121241899370.png b/docs/troubleshooting/assets/20250430121241899370.png new file mode 100644 index 00000000..c56fdb46 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121241899370.png differ diff --git a/docs/troubleshooting/assets/20250430121242149430.png b/docs/troubleshooting/assets/20250430121242149430.png new file mode 100644 index 00000000..553f9ffc Binary files /dev/null and b/docs/troubleshooting/assets/20250430121242149430.png differ diff --git a/docs/troubleshooting/assets/20250430121242530889.png b/docs/troubleshooting/assets/20250430121242530889.png new file mode 100644 index 00000000..faf628bf Binary files /dev/null and b/docs/troubleshooting/assets/20250430121242530889.png differ diff --git a/docs/troubleshooting/assets/20250430121242814005.png b/docs/troubleshooting/assets/20250430121242814005.png new file mode 100644 index 00000000..83b5788c Binary files /dev/null and b/docs/troubleshooting/assets/20250430121242814005.png differ diff --git a/docs/troubleshooting/assets/20250430121532523511.png b/docs/troubleshooting/assets/20250430121532523511.png new file mode 100644 index 00000000..1ffa65e3 Binary files /dev/null and b/docs/troubleshooting/assets/20250430121532523511.png differ diff --git a/docs/troubleshooting/assets/20250430121532793176.png b/docs/troubleshooting/assets/20250430121532793176.png new file mode 100644 index 00000000..97153aaf Binary files /dev/null and b/docs/troubleshooting/assets/20250430121532793176.png differ diff --git a/docs/troubleshooting/backend-issues/_category_.json b/docs/troubleshooting/backend-issues/_category_.json new file mode 100644 index 00000000..3e4fed67 --- /dev/null +++ b/docs/troubleshooting/backend-issues/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Backend" +} \ No newline at end of file diff --git a/docs/troubleshooting/backend-issues/listview_gray_box_and_red_screen_errors.md b/docs/troubleshooting/backend-issues/listview_gray_box_and_red_screen_errors.md new file mode 100644 index 00000000..03b083f8 --- /dev/null +++ b/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. +::: + diff --git a/docs/troubleshooting/backend-issues/listview_returning_only_one_item.md b/docs/troubleshooting/backend-issues/listview_returning_only_one_item.md new file mode 100644 index 00000000..d0b72088 --- /dev/null +++ b/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. +::: \ No newline at end of file diff --git a/docs/troubleshooting/backend-issues/resolving_firebase_configuration_issues.md b/docs/troubleshooting/backend-issues/resolving_firebase_configuration_issues.md new file mode 100644 index 00000000..59f8225e --- /dev/null +++ b/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 `firebase@flutterflow.io` 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 `firebase@flutterflow.io` 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. +::: \ No newline at end of file diff --git a/docs/troubleshooting/backend-issues/update_document_action_fails_during_backend_call.md b/docs/troubleshooting/backend-issues/update_document_action_fails_during_backend_call.md new file mode 100644 index 00000000..0b546c72 --- /dev/null +++ b/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) +::: \ No newline at end of file