Test Mode

docs/troubleshooting/migrate-issues/_category_.json

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

docs/troubleshooting/migrate-issues/black_screen_during_run_mode.md

@@ -0,0 +1,42 @@
+---
+keywords: ['run-mode', 'black-screen', 'preview']
+slug: /black-screen-during-run-mode
+title: Black Screen During Run Mode
+---
+
+# Black Screen During Preview
+
+If your app screen appears blank during Run Mode, follow these steps to resolve the issue:
+
+:::info[Prerequisites]
+- You have already built and deployed at least one screen in your FlutterFlow project.
+- You are running the app in **Run Mode** within the FlutterFlow editor.
+:::
+
+1. **Reload the Frame**
+
+    Right-click on the preview screen and select **Reload Frame**.
+
+2. **Change the Device**
+
+    Use the device selector on the left panel to switch to a different preview device.
+
+3. **Refresh the Page**
+
+    Press `Ctrl + R` (Windows) or `Cmd + R` (Mac) to refresh the browser.
+
+4. **Update FlutterFlow and Clear Cache**
+
+    - Ensure you are using the latest version of FlutterFlow.
+    - Clear your browser cache.
+    - Log out and back in to your FlutterFlow account.
+
+5. **Submit a Bug Report**
+
+    If none of the steps work, submit a bug report using the **Send Feedback** button in FlutterFlow.
+
+    ![](../assets/20250430121528287666.png)
+
+:::tip
+Blank screens are often temporary. Try switching devices or reloading before making major changes to your project.
+:::

docs/troubleshooting/migrate-issues/firestore_permission_error-run_mode.md

@@ -0,0 +1,70 @@
+---
+keywords: ['notification', 'security', 'permissions']
+slug: /firestore-permission-error-run-mode
+title: Firestore Permission Error in Run Mode
+---
+
+# Firestore Permission Error in Run Mode
+
+When previewing your app in Run Mode, you may encounter the following error message:
+
+**Firestore Security Rules: Missing or insufficient permissions**
+
+This occurs when your Firestore rules conflict with the permissions required for a query in your app.
+
+:::info[Prerequisites]
+- You are using Firebase Firestore in your FlutterFlow project.
+- Your project has one or more Firestore queries configured.
+:::
+
+
+This error is typically triggered when:
+
+  - Firestore rules prevent any user from reading the database.
+  - A page attempts to run a query before a user is authenticated (e.g., querying user-specific data on the login page).
+
+  Example:
+
+  - If Firestore rules are configured as:
+
+    ```js
+    rules_version = '2';
+    service cloud.firestore {
+      match /databases/{database}/documents {
+        match /{document=**} {
+          allow read, write: if false;
+        }
+      }
+    }
+    ```
+
+    Any Firestore query will fail because no read or write access is allowed.
+
+  - If rules allow only authenticated access:
+
+      ```js
+      allow read, write: if request.auth != null;
+      ```
+
+    And a query is placed on a page before the user signs in (e.g., on the login screen), it will trigger this error.
+
+    Descriptive widget names can help you quickly identify which query or widget is triggering the permission issue. In the example above, the error message references a widget named Container. Renaming it to something like UserQueryContainer can make debugging easier.
+
+Take the steps below to fix this error:
+
+  - **Review Firestore Rules**
+
+    Go to Firestore → Settings → Rules and verify that your access rules align with how and when your app queries the database.
+
+  - **Adjust Query Placement**
+
+    Ensure that queries requiring authentication are not used on screens accessible to unauthenticated users.
+
+  - **Use Conditional Visibility**
+
+    If a query must exist on a pre-login screen, wrap it in conditional logic to only execute when the user is signed in.
+
+:::tip
+Test queries using the Run Mode Console and check the browser logs for more specific errors.
+Use Firestore Schema Validation in FlutterFlow to ensure your rules are properly deployed.
+:::

docs/troubleshooting/migrate-issues/gray_screen_run_mode.md

@@ -0,0 +1,103 @@
+---
+keywords: ['firebase', 'configuration', 'gray-screen']
+slug: /gray-screen-run-mode
+title: Gray Screen in Run Mode
+---
+
+# Gray Screen in Run Mode
+
+Seeing a gray screen in FlutterFlow’s Run Mode usually points to a configuration issue in your Firebase or project settings. Follow these steps to diagnose and resolve the issue.
+
+:::info[Prerequisites]
+- You have integrated Firebase with your FlutterFlow project.
+- You have access to your Firebase Console.
+:::
+
+1. **Check Firebase Permissions**
+
+    Ensure that `[email protected]` has the following roles:
+
+    - **Editor**
+    - **Cloud Functions Admin**
+    - **Service Account User**
+
+    To verify:
+
+        1. Go to the **Firebase Console**.
+        2. Select your project → **Project Overview**.
+        3. Navigate to **Users and permissions** → **Advanced permissions**.
+        4. Locate `[email protected]` and ensure it has the roles listed above.
+
+            ![](../assets/20250430121529462395.png)
+
+        If missing, click the pencil icon and assign the roles.
+
+2. **Regenerate Firebase Configuration Files**
+
+    1. In FlutterFlow, go to **Settings & Integrations** → **Firebase**.
+    2. Click **Regenerate Config Files**.
+    3. In the popup, click **Generate Files**.
+
+        ![](../assets/20250430121530070855.png)
+
+        :::tip
+        You must regenerate config files if you change your project name in FlutterFlow or Firebase.
+        :::
+
+3. **Update Firebase Rules**
+
+    1. In FlutterFlow, go to **Firestore** → **Settings**.
+    2. Scroll to **Firestore Rules** and click **Deploy**.
+    3. Confirm by selecting **Deploy Now** in the popup.
+
+    ![](../assets/20250430121530401837.jpg)
+
+    A green checkmark indicates success.
+
+4. **Validate Firebase Schema**
+
+    1. In **Firestore** → **Settings**, scroll to **Firebase Schema Validation**.
+    2. Click **Validate**.
+
+        ![](../assets/20250430121530999303.jpg)
+
+        If the schema is valid, you’ll see a success message. If not, review the identified issues.
+
+        ![](../assets/20250430121531448037.png)
+
+5. **Ensure Collections Have Data**
+
+    An empty Firestore collection can result in a gray screen. Visit the Firebase Console → **Firestore Database** to confirm your collections contain documents.
+
+    ![](../assets/20250430121531723554.png)
+
+6. **Verify Custom Widget Compatibility**
+
+    If your app uses a custom widget, make sure its package supports web. On **[pub.dev](https://pub.dev)**, check that **WEB** is listed under platforms.
+
+    ![](../assets/20250430121531973906.png)
+
+    If not, choose an alternative package.
+
+7. **Refresh FlutterFlow Environment**
+
+    - Press `Ctrl + R` (Windows) or `Cmd + R` (Mac) to refresh FlutterFlow.
+    - Clear your browser cache.
+    - Log out and back in.
+
+        :::tip
+        Refreshing your session can fix slow or buggy behavior in the UI Builder.
+        :::
+
+8. **Retest the Project**
+
+    After completing the above steps, create a new Run Mode session to test if the gray screen issue is resolved.
+
+9. **Test Locally**
+
+    If the issue persists, download your FlutterFlow code and run the project locally to diagnose further.
+
+:::info[Additional Resources]
+- **[Run Flutter App Locally](/testing/local-run)**
+- **[FlutterFlow Firebase Integration Guide](/integrations/firebase/connect-to-firebase/#step-1-set-up-your-project)**
+:::

docs/troubleshooting/migrate-issues/loading_spinner_run_mode.md

@@ -0,0 +1,41 @@
+---
+keywords: ['database', 'firestore', 'loading']
+slug: /loading-spinner-run-mode
+title: Loading Spinner in Run Mode
+---
+
+# Loading Spinner in Run Mode
+
+A persistent loading spinner in FlutterFlow's Run Mode usually indicates an issue with your Firestore rules configuration. Updating your rules can resolve this issue.
+
+:::info[Prerequisites]
+- You have already connected your FlutterFlow project to Firebase.
+- You have access to your Firebase Console.
+:::
+
+Here are the steps to fix this error:
+
+1. **Copy Firestore Rules from FlutterFlow**
+
+    1. Open your FlutterFlow project.
+    2. Navigate to **Firestore** → **Settings**.
+    3. Click the **Copy** icon to copy the default Firestore rules.
+
+    ![](../assets/20250430121355282620.gif)
+
+2. **Paste the Rules in Firebase Console**
+
+    1. Open the **[Firebase Console](https://console.firebase.google.com/)**.
+    2. Select your project and go to **Firestore Database**.
+    3. Open the **Rules** tab.
+    4. Paste the copied rules into the editor and click **Publish**.
+
+    ![](../assets/20250430121355575413.gif)
+
+3. **Retest Your Project in FlutterFlow**
+
+    Return to FlutterFlow and run your project again in **Run Mode**. The loading spinner should no longer appear if the Firestore rules were configured correctly.
+
+:::tip
+Always keep your Firestore rules up to date after making structural changes to your database in FlutterFlow.
+:::

docs/troubleshooting/migrate-issues/local_build_providerinstaller_error.md

@@ -0,0 +1,51 @@
+---
+keywords: ['build', 'android', 'emulator']
+slug: /local-build-providerinstaller-error
+title: Local Build ProvuderInstaller Error
+---
+
+# Local Build ProvuderInstaller Error
+
+This error commonly occurs when building Flutter apps on Android emulators. It is related to the `ProviderInstaller` service and can typically be resolved through basic cleanup and Flutter version upgrades.
+
+:::info[Prerequisites]
+- You are testing or running your Flutter project on an Android emulator.
+- You have Flutter and Android Studio installed and configured.
+:::
+
+1. **Uninstall the App from the Emulator**
+
+    Before rebuilding your app, ensure the old installation is removed:
+
+    1. Open the Android Emulator.
+    2. Locate your app icon and uninstall it.
+    3. Alternatively, run the following command from your terminal:
+
+        ```bash
+        adb uninstall com.yourcompany.yourapp
+        ```
+
+            Replace com.yourcompany.yourapp with your actual app ID.
+
+2. **Rebuild the App**
+    After uninstalling:
+
+    Run the following command in your project directory:
+
+        flutter clean
+        flutter pub get
+        flutter run
+
+
+        This will remove cached data and reinstall the app on the emulator.
+
+3. **Upgrade Flutter (If Problem Persists)**
+
+    If the issue continues, upgrading Flutter may help:
+        flutter upgrade
+
+    Ensure your Flutter SDK is up to date. You can verify the version with:
+
+        flutter --version
+
+    This error is often related to Google Play Services not being properly initialized on the emulator. If you're still encountering issues, consider creating a new emulator using a system image that includes the Play Store.

docs/troubleshooting/migrate-issues/slow_test_mode_load.md

@@ -0,0 +1,50 @@
+---
+keywords: ['test mode', 'slow load', 'run mode']
+slug: /slow-test-mode-load
+title: Slow Loading in Test Mode
+---
+
+# Slow Loading in Test Mode
+
+If Test Mode takes several minutes to load or fails entirely, the issue may stem from your browser, network, or project configuration. This guide walks you through the most common causes and how to resolve them.
+
+:::info[Prerequisites]
+- You are using FlutterFlow's Test Mode feature.
+- You have already deployed or previewed a version of your app.
+:::
+
+Below are the common causes and fixes:
+
+- **Check Your Internet Connection**
+
+    A weak or unstable connection may delay the loading of compiled apps. Make sure you have a stable network before launching Test Mode.
+
+- **Sync Your System Clock**
+
+    Ensure your device’s time and date settings are accurate. An incorrect clock can cause authentication issues and impact performance.
+
+- **Clear Browser Cache**
+
+    Browsers store temporary files that may interfere with page loading. Clearing your cache can resolve stale resource conflicts and improve speed.
+
+- **Try a Different Browser**
+
+    Some browsers may conflict with specific web assets or settings. If one browser is slow, switch to another (e.g., from Chrome to Firefox).
+
+- **Disable Browser Extensions**
+
+    Extensions like ad blockers or privacy tools can interfere with FlutterFlow’s platform. Temporarily disable them to check for improvement.
+
+:::tip[Optimize Your Project]
+Projects with many pages, assets, or custom code can take longer to compile.
+- Remove unused images, fonts, or icons.
+- Consolidate or simplify custom code.
+- Limit the number of pages in a single testing session.
+:::
+
+:::info[Additional Resources]
+If the issue persists after following the steps above, check the official support article:  
+**[FlutterFlow: Test Mode Is Not Loading or Is Very Slow](https://intercom.help/flutterflow/en/articles/7052737-test-mode-is-not-loading-or-is-very-slow-it-takes-a-long-time-to-load-the-app)**
+:::
+
+Following these steps should resolve most Test Mode performance issues and reduce load times for future previews.