You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/troubleshooting/backend-issues/listview_gray_box_and_red_screen_errors.md
+45-42Lines changed: 45 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,73 +6,76 @@ title: ListView Gray Box and Red Screen Errors
6
6
7
7
# ListView Gray Box and Red Screen Errors
8
8
9
-
**Issue**
9
+
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.
10
10
11
-
When trying to load a list of items from the database, the list doesn't load and displays a gray box.
12
-
13
-
**Cause**
14
-
15
-
A gray box means the backend query failed and couldn't return any result.
11
+
:::info[Prerequisites]
12
+
- Ensure your query is correctly connected to a Firestore collection or CMS.
13
+
- Confirm that your app builds and runs correctly in **Run** and **Test** modes.
14
+
:::
16
15
17
-
**Verifying Query Functionality**
16
+
**Understanding the Error:**
18
17
19
-
- If the query is successful and returns items, you will see the list populated.
20
-
- If there are no records matching the query, but the query itself is successful, you will see the **empty state** that you have configured for your list.
18
+
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.
21
19
22
-
20
+
**Step-by-Step Troubleshooting:**
23
21
24
-
:::tip
25
-
Always configure an empty state for lists. This helps differentiate between an empty dataset and a failed query.
26
-
:::
22
+
1.**Verify Query Results**
27
23
28
-
**Behavior in Different Modes**
24
+
- If the query is successful and returns items, the list will populate as expected.
25
+
- If there are no records matching the query, you will see the **empty state** you configured.
26
+
- If the query fails, a gray box (in Run mode) or a red error screen (in Test mode) will appear.
29
27
30
-
The behavior may differ depending on whether you are in **Run** or **Test** mode:
If you are seeing a gray box and no filters or ordering are applied to your query, the issue is likely with the data itself, specifically **null values** in your database.
47
+
Null values in critical fields may cause queries or widgets to fail.
46
48
47
-
Null values can cause FlutterFlow queries to fail.
49
+
Here is how to check for null values:
48
50
49
-
51
+
1. Inspect your data in **Firebase** or **CMS** for any fields with `null` values.
52
+
2. Pay attention to fields used in filters, formatting, or conditional visibility.
53
+
3. For example, if `created_time` is null and you are formatting a date from this field, the query may fail.
50
54
51
-
**How to Check for Null Values**
55
+
**Example: Null Field Causing Error**
52
56
53
-
- Inspect your data in Firebase for any fields that have null values.
54
-
- If your dataset is small, you can use the FlutterFlow CMS to review the data.
57
+
For example, in the image below, the `created_time` field is null. If your widget relies on this field (e.g., formatting the date), the query will fail.
60
+
:::note
61
+
Use **visibility rules** to hide widgets that depend on potentially null values.
If you are performing document-from-reference queries inside an item widget, always add a visibility rule to that widget. This prevents the query from breaking if the reference field is empty.
69
-
:::
70
+
:::note
71
+
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.
72
+
:::
70
73
71
74
72
75
:::info[Summary]
73
-
- A gray box means the query failed.
74
-
- A red screen means an error occurred in test mode.
75
-
- Null values in your data are a common cause.
76
-
- Always configure empty states and use visibility rules to handle null data safely.
76
+
- A **gray box** means the backend query failed.
77
+
- A **red screen** indicates a runtime error in **Test mode**.
78
+
-**Null values** in your database are a common cause of failure.
79
+
- Always configure **empty states** and apply **visibility rules** to handle null or missing data gracefully.
If your **ListView** is only returning one item in FlutterFlow, check the following possible causes:
8
+
If your **ListView** is only showing one item, this guide will walk you through the common reasons and how to resolve the issue.
9
9
10
-
-**Use a Dynamic Widget**: Ensure you are using a dynamic widget such as **ListView**, **GridView**, **Row**, or **Column** to dynamically generate multiple children.
10
+
:::info[Prerequisites]
11
+
- A working Firebase or CMS integration.
12
+
- A dynamic layout widget such as `ListView`, `GridView`, or `Column`.
13
+
- At least two documents in your Firestore collection for testing.
14
+
:::
11
15
12
-
-**Query for a List**: Confirm that your query retrieves a **list of documents** rather than a single record.
16
+
Follow the steps below to resolve the issue:
13
17
14
-
-**Check Filters**: If you're applying filters, make sure that your Firestore database contains **multiple records** that satisfy the filter conditions.
18
+
1.**Use a Dynamic Widget**
19
+
Make sure you're using a widget like `ListView`, `GridView`, or `Column` that supports dynamic content.
15
20
16
-
-**Sufficient Records**: Verify that your Firestore collection has **enough records** to display multiple items.
21
+
2.**Confirm the Query Type**
22
+
Ensure the query is set to return a **list of documents**, not a single document.
17
23
18
-
-**List Type Field**: If you are querying a single field, ensure that it’s defined as a **ListType field** in both FlutterFlow and Firebase.
24
+
3.**Review Applied Filters**
25
+
If you are using filters, check that multiple records in your database satisfy those filter conditions.
19
26
20
-
By carefully reviewing these areas, you should be able to resolve the issue of your ListView returning only one item.
27
+
4.**Check Firestore Data**
28
+
Open your Firestore collection and verify that it contains **multiple records**.
29
+
30
+
5.**Verify List Type Fields**
31
+
If querying a single field, confirm it's defined as a **List** in both Firebase and FlutterFlow.
32
+
33
+
:::tip
34
+
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.
If you are facing issues related to the backend in FlutterFlow, follow these steps to ensure your Firebase setup is correctly configured:
8
+
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.
9
9
10
-
-**Add Proper Cloud Permissions**
10
+
:::info[Prerequisites]
11
+
- You must have already connected your Firebase project to FlutterFlow.
12
+
- You should have access to your Firebase console with admin rights.
13
+
:::
11
14
12
-
Grant the following permissions to **firebase@flutterflow.io** in your Firebase project:
15
+
Follow the steps below to fix firebase configuration:
13
16
14
-
- **Editor**
15
-
- **Cloud Functions Admin**
16
-
- **Service Account User**
17
+
1.**Grant Required Permissions**
17
18
18
-
Learn how to **[assign Firebase permissions](/integrations/firebase/connect-to-firebase/#allow-flutterflow-to-access-your-project)**.
19
+
Assign the following permissions to `[email protected]` in your Firebase project:
20
+
- Editor
21
+
- Cloud Functions Admin
22
+
- Service Account User
19
23
20
-
-**Update Firebase Rules**
24
+
Learn how to **[assign Firebase permissions](/integrations/firebase/connect-to-firebase/#allow-flutterflow-to-access-your-project)**.
21
25
22
-
Ensure that your Firebase Firestore security rules are updated correctly. See how to **[update Firebase rules](/integrations/database/cloud-firestore/firestore-rules/)**.
26
+
2.**Update Firestore Rules**
23
27
24
-
After updating the rules, delete **[email protected]** from your authenticated users, redeploy the Firestore rules, and validate the schema again.
28
+
Update your Firestore security rules to allow access for FlutterFlow.
Verify that all data field types and field names match between **Firestore** and **FlutterFlow**.
37
+
3.**Match Field Types and Names**
31
38
32
-
-**Validate Firestore Schema**
39
+
Check that data field types and names match between Firestore and FlutterFlow exactly. Mismatches will cause query errors.
33
40
34
-
Use the **Validate** button in **Firestore → Settings** inside FlutterFlow to confirm that the Firestore collection schema matches the FlutterFlow configuration.
41
+
4.**ValidateFirestore Schema in FlutterFlow**
35
42
36
-
43
+
Use the **Validate** button under **Firestore → Settings** in FlutterFlow to confirm that your collection schema matches your Firestore structure.
37
44
38
-
-**Reset Firebase Setup (If Needed)**
45
+
39
46
40
-
If you have already completed the Firebase setup but continue to experience issues, remove existing permissions and complete the setup process from scratch.
Copy file name to clipboardExpand all lines: docs/troubleshooting/backend-issues/update_document_action_fails_during_backend_call.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ When the update action fails, the action flow stops, preventing any subsequent a
21
21
22
22
There are two common reasons why the update action may fail:
23
23
24
-
1.**Permission Issue in Firestore**
24
+
-**Permission Issue in Firestore**
25
25
26
26
The user may not have the necessary permission to write to the document.
27
27
@@ -33,7 +33,7 @@ There are two common reasons why the update action may fail:
33
33
**Solution:**
34
34
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.
35
35
36
-
2.**Data Type Mismatch**
36
+
-**Data Type Mismatch**
37
37
38
38
The values you are attempting to write may not match the expected field types.
0 commit comments