FlutterFlow Not Working? Fix the 10 Most Common Errors (2026)

Jump to: quick triage · stuck on splash · auth fails on release · Firestore permissions · API errors · store rejection · app lag · custom code won't compile · Supabase UUID errors · images not loading · exported code won't build · common misunderstandings · FAQ

Start Here: 2-Minute FlutterFlow Triage

Before treating anything below as one of the 10 problems, rule out the causes that look the same from the outside but have a different fix.

See the official basic troubleshooting guide for the full walkthrough of the debug console and the Debug info panel. Everything from here on assumes the editor itself loads and you can reproduce the problem.

Error 1 - App Stuck on the Splash or Loading Screen After Publishing

What you see: the app hangs on the splash or loading screen after you publish or run it, with no visible error.

Why it happens

A "stuck loading" screen is usually a hidden failure, not a frozen app: an action or query fails silently and the loading state never resolves because nothing tells the app to move past it. FlutterFlow surfaces some of these as a "Run mode-only notification" in a snack bar rather than a hard crash, which is easy to miss if you're not watching for it.

How to fix it

1. Open the browser debug console at the moment the app should finish loading and look for a red error.
2. Run the app in Test Mode and open the Debug info panel to check whether the variable controlling the loading state is the one staying null or unset.
3. For a local run, check the device logs instead of the browser console; the error that explains the hang is often there.

What you should see: the console or Debug info panel points to the specific action or variable causing the hang, instead of a blank loading screen with no clue.

Error 2 - Firebase Authentication Failing Only on the Released Build

What you see: sign-in works in Test Mode or the FlutterFlow preview, but fails once you publish the app or build it yourself from exported code.

Why it happens

A released build runs under a different domain, bundle ID, or signing fingerprint than the editor's own preview. Firebase Authentication checks that domain, ID, or fingerprint against an allow-list, so a build that was never added to that list gets rejected even though the same sign-in flow worked fine during testing.

How to fix it

1. In the Firebase console, under Authentication > Settings > Authorized domains, confirm your production domain is listed, not just the FlutterFlow preview domain.
2. For Android, confirm the SHA-1 and SHA-256 fingerprints for your release signing key, not only your debug key, are registered in the Firebase project settings.
3. For provider-specific setup (Google, Apple, email link) and the exact screens involved, see the dedicated FlutterFlow Firebase auth guide.

What you should see: sign-in succeeds in the released build the same way it did in Test Mode.

Error 3 - Firestore Security Rules Blocking Reads

What you see: a "Run mode-only notification" reading Missing or insufficient permissions, even though the data exists in Firestore.

Why it happens

FlutterFlow's own documentation on this error gives two causes: the Firestore rules don't allow any user to read that collection, or a page runs a query before the user is actually authenticated, such as requesting user-specific data on the login page itself.

How to fix it

1. In the Firebase console, under Firestore Database > Rules, confirm the rule for that exact collection path allows a read for the signed-in user's role.
2. If the failing query runs on a page that loads before sign-in finishes, gate it behind a check that the user is actually authenticated instead of firing it immediately on page load.
3. For a line-by-line walkthrough of writing rules that work with FlutterFlow's query patterns, see the dedicated Firestore rules guide.

What you should see: the read succeeds and the notification stops appearing in Run Mode.

Error 4 - API Call Returning an Error Only in Test or Released App

What you see: an API call succeeds in FlutterFlow's own API test panel, but fails once the same call runs inside the app in Test Mode or after release.

Why it happens

The test panel often has headers, tokens, or variables filled in by hand that aren't actually being passed the same way at runtime, or the call depends on app state (like a signed-in user) that only exists once a real session is running, not while testing the endpoint in isolation.

How to fix it

1. Compare the request as it's actually sent at runtime against what you tested manually, specifically headers and auth tokens.
2. Confirm every variable used in the request body or URL has a real value at the moment the call fires, not a null placeholder.
3. For a full walkthrough of debugging API calls step by step, see the dedicated API integration guide.

What you should see: the call returns the same result inside the app that it did in the test panel.

Error 5 - App Store or Play Store Rejection

What you see: the app gets rejected during review, commonly for crashing on launch or because the reviewer couldn't get past a login screen.

Why it happens

Reviewers test on devices and account states you may not have tried yourself. One reported case traced a repeated "crashes on launch" rejection back to conditional visibility logic meant for desktop screens, which broke on the reviewer's device; Apple's own rejection message gave no more detail than the crash itself.

How to fix it

1. Test the exact path a reviewer would take: a fresh install, signed out, on the smallest supported OS version and device size you claim to support.
2. If the app requires an account, provide working demo credentials or a demo mode; a reviewer who can't sign in can't approve the app.
3. Review any conditional visibility logic tied to device type or screen width. It's a common, easy-to-miss cause of a crash that only shows up on devices you didn't personally test.
4. For the full submission checklist, see the dedicated app store rejection guide.

What you should see: the app passes review on the first or second resubmission, with no crash-on-launch or access reports.

Error 6 - App Lag and Jank as Lists Grow

What you see: the app felt smooth with a handful of test rows, then starts stuttering once real data loads a long list.

Why it happens

A list that renders every row up front, or a query that re-runs on every rebuild, scales fine with a handful of test records and badly once the list holds hundreds of real ones.

How to fix it

1. Confirm the list widget uses lazy, builder-style rendering rather than building every row immediately.
2. Move expensive queries out of a per-item builder so they run once, not once per row.
3. For the full set of causes and fixes, see the dedicated app lag guide.

What you should see: scrolling stays smooth as the list grows to a realistic size.

Error 7 - Custom Action or Custom Code Failing to Compile

What you see: an Unknown error compiling custom code message that doesn't point to a specific line.

Why it happens

FlutterFlow's own build-failure documentation notes that a build can fail when a package or piece of custom code doesn't support the platform you're targeting. Separately, a repeated pattern in community reports is that this generic message appears when a custom action or widget's name in the code doesn't match the name set for it in the editor.

How to fix it

1. Check that the custom action or widget's function name in the code matches exactly what's set in the FlutterFlow editor, including case.
2. Verify on pub.dev that any package you added supports every platform you're building for, not just the one you tested on.
3. Paste the custom code into a throwaway local Flutter project and try to compile it there. If it fails locally too, the problem is in the code, not FlutterFlow.

What you should see: the custom code compiles, or the local test points you to the actual line at fault.

Error 8 - Supabase Type and UUID Mismatches

What you see: an insert or update to a Supabase table fails with an error like invalid input syntax for type uuid.

Why it happens

This is Postgres error 22P02. A reported case traced it to an action sending an empty value for a UUID column, or linking a column of one type (such as an integer ID) to a column that expects a UUID, such as Supabase's own auth user ID.

How to fix it

1. In the FlutterFlow action's field mapping, stop sending a value for any UUID column that already has a database default, such as id, and let Postgres generate it instead.
2. If the error points to a foreign key, confirm both sides of the relationship use the same column type. Linking an integer column to a UUID column, including Supabase's own auth user ID, is what triggers this error, and the fix is matching types on both sides, not forcing the insert through.
3. Don't work around the error by widening table permissions or using an admin-level key inside the app. A permissive rule hides the mismatch instead of fixing it, and an admin key doesn't belong in a distributed app.

What you should see: the insert or update succeeds without the type error.

Error 9 - Images or Assets Not Loading on Device

What you see: an image shows correctly in the FlutterFlow builder and in the browser preview, but is missing or blank on an actual phone or tablet.

Why it happens

A reported case found the asset flagged as "unlinked" on the Media Assets page despite still working in the browser; deleting and re-uploading an asset under the same name is a common way to break that link without noticing.

How to fix it

1. Open the Media Assets page and check whether the specific image shows as unlinked; if it does, re-select it on the widget that uses it.
2. Rebuild and reinstall the app on the device rather than relying on a hot reload. A stale build can keep referencing a deleted asset's old path.

What you should see: the image loads on device the same way it does in the browser preview.

Error 10 - Exported Code That Will Not Build Locally

What you see: flutter pub get or flutter run fails in your own editor on code downloaded from FlutterFlow, even though the project ran fine in Test Mode or Run Mode.

Why it happens

FlutterFlow's own documentation on downloaded code points to a mismatch between the Flutter SDK version installed on your machine and the version FlutterFlow built the project against as the most common cause, not a bug in the exported code itself. The same platform-support issue behind error 7 can also show up here when a package or custom code doesn't support your local target platform.

How to fix it

1. Compare your local flutter --version output against the Flutter version listed on the project's export or settings screen.
2. Run flutter clean followed by flutter pub get inside the exported folder before opening it in your editor.
3. If a specific package or piece of custom code is the failure, confirm on pub.dev that it supports your local build target, the same check as error 7.
4. For the full local setup workflow, see the dedicated export code guide.

What you should see: the exported project builds locally without the version or platform-support errors.

Common Misunderstandings About FlutterFlow

• Test Mode and a released, published, or exported build don't always behave the same way. Auth, API calls, and permission checks that pass in Test Mode can fail in a real release because of what each environment is actually allowed to reach.
• A build failing locally isn't proof FlutterFlow itself is broken. Most local-only failures trace back to a mismatched Flutter SDK version or a package that doesn't support your target platform, both of which are fixable on your own machine.
• An "Unknown error compiling custom code" message without a line number isn't FlutterFlow withholding information. Checking that the action or widget's name matches the editor first resolves it in the most commonly reported cases.
• Opening Firestore or Supabase permissions to everyone makes the error message disappear, but it isn't a fix. It leaves the database open to any request, not just the one that was failing.

When It Isn't a Bug

• A build refusing to compile because a package doesn't support your target platform is FlutterFlow doing its job, not malfunctioning.
• An App Store or Play Store rejection for incomplete reviewer access, such as no working demo account, is store policy being enforced, not a FlutterFlow problem.
• "Run mode-only notifications" exist specifically to surface errors in testing that a real user would otherwise hit first, after the app is already live.

What to Include When You Ask for Help

• The exact error text, not a paraphrase, including any error code (such as 22P02).
• Whether it happens in Test Mode, Run Mode, after publishing, or only in exported code run locally.
• What the browser debug console or Debug info panel showed at the moment it failed.
• For a local build issue, both your local flutter --version and the Flutter version shown on the project's export screen.

FlutterFlow not working: quick answers

Sources

• Basic troubleshooting guide - FlutterFlow, consulted 2026-10-22
• Firestore permission error in Run Mode - FlutterFlow, consulted 2026-10-22
• Run Mode: build failure - FlutterFlow, consulted 2026-10-22
• Resolve errors in downloaded code - FlutterFlow, consulted 2026-10-22
• Authentication FAQ and troubleshooting - Firebase, consulted 2026-10-22
• AppStuck's FlutterFlow page for what else can go wrong once the app is working correctly