Basic Troubleshooting Guide

This is a general troubleshooting or debugging guide for any issues that occur with FlutterFlow projects.

Detecting issue

If you're experiencing issues running your project in Run/Test Mode, downloading the APK/Code, or pushing to GitHub, it could be related to a widget or configuration error within your project. We've improved our issue detection capabilities to provide clearer insights into what might be causing these problems.

We log the issues in a browser's debug console, desktop app's device logs, display it in a popup, or show it while your app is running. If you don't see any popups and want to figure out what's wrong, you can open the logs.

1. Opening debug logs

To open the debug logs, run your app in Run/Test mode and select:

For Google Chrome

Windows: F12 or Ctrl+Shift+J
Mac: F12 or ⌘+Option+J

For Safari

Go to Preferences/Settings > Advanced and enable the "Show Develop menu". Then, use ⌘+Option+C to open the console.

This will open the console log, and any errors will be highlighted in red color.

2. Desktop app's device logs

If you're using our Desktop App and running the app with a local run, you might encounter issues that are logged in the device logs. These logs can help you understand why something isn't working as expected.

For example, if a user enters a character instead of a numeric value for the product quantity, which is not allowed, the error will be logged in the device logs, highlighting the exact issue.

If you're unsure about the meaning of an error message, you can copy and paste the entire error text into ChatGPT and ask for an explanation or solution.

For this specific error, we asked ChatGPT to explain and guide us on fixing the issue, and the fix was super simple!

If you see a popup, open the red-colored section (click Read More), and at the bottom, you will see the exact widget or error causing the build or download failure.

Let's see a couple of examples of what you might encounter while building your app:

Example 1

Suppose you have a Text widget and added an action that is incomplete. When you try to download the project in such a situation, you might see the following:

To track down the error-causing widget in the widget tree, start reading the widget list (from top to bottom in a popup) and locate the widget using its child number. For example, when a widget is displayed as Child 1, it will be the first child of its previous widget (see the widget in a popup). And when it is shown as Child 2,3, and so on, it will be the sibling widget of Child 1.

If you have a practice of naming the widget, it will be straightforward to track it down (as we'll display the exact widget name). Here is how it looks:

To find out what caused the widget to fail, you can check errors in the project issues.

Example 2

Let's say you have added a custom widget that works fine. But while modifying it, you made some typo in the code, and now it shows this:

The second "Error:" line clearly mentions that there is some issue with a method name in a custom code.

4. Runtime errors (Run mode-only notification)

Runtime errors in app development are errors that occur during the execution of the app. Unlike the errors that we display while you build the app, runtime errors occur while the app is running.

For instance, if Firestore security rules aren't properly configured, the app might run into permission issues at runtime, leading to failures in data retrieval or display. This kind of error might not be evident during app building but becomes apparent only when the app interacts with the Firestore database during actual operation.

We display such errors as Run mode-only notification in a snack bar. Here's what it might look like:

Frontend (UI builder) issues

The following steps will help you fix the issues with the UI builder inside FlutterFlow.

In case of overflowing text, it's recommended that you wrap the Text Widget inside an Expanded widget. To do this, click on the Expand option in the alignment properties of the Text Widget.
If you notice scaling issues with widgets, please ensure that you set percentage values for the dimensions of the widgets.
When renaming a custom widget or custom action, please make sure that you rename the widget from the code as well.
Please ensure not to upload duplicate media assets in the Project Media Assets.
Make sure you've entered the correct API keys when using third-party integrations.
Clear your browser cache and history if FlutterFlow seems to be laggy.
Change the browser or use incognito/private browsing mode if you cannot start from the login screen when using the Test/Run mode.

Backend issues

The following steps will help you fix the issues like Grey Screen error, Infinite Loading screen, Firestore record creating error, etc. These common steps are recommended to perform for any issue faced with the backend.

Ensure you have added the following cloud permissions for firebase@flutterflow.io: Editor, Cloud Functions Admin, and Service Account User. Here are instructions on how to do this.
Update your Firebase rules. Here are instructions on how to do this.
Ensure all the data field types and names match in Firestore and FlutterFlow. Here are instructions on how to do this.
If you have already completed the Firebase setup, remove the existing permissions and complete a new setup from scratch. Here are instructions on how to do this.
Make sure you've added app.flutterflow.io to Authorized Domains under the authentication tab in Firebase.
Ensure you are on the latest version of FlutterFlow by selecting (ctrl/cmd + R). After you have done this, clear your browser cache and log out/into FlutterFlow.
To use Cloud Functions like Push Notifications, Payments, etc. Please make sure your Firebase project is on a Blaze Plan.