How to fix “App freezes with no error” — self-help for Custom Widgets & Custom Functions

Note: FlutterFlow does not provide support for custom code (Custom Widgets, Custom Functions, or Custom Actions). The guidance below summarizes the most common causes and proven fixes so you can diagnose and resolve freezes yourself. If you determine the freeze is caused by a built-in FlutterFlow widget or action, feel free to contact support and include the artifacts listed in When to contact support.

Quick summary

If a page or the entire app becomes unresponsive with no error message, the most likely causes when custom code is present are:

an infinite loop,
missing await / incorrect async handling, or
heavy synchronous CPU work on the UI thread.

Follow this sequence: Prepare → Minimal repro → Isolate → Instrument → Fix → Verify. Test on a device or test build (not Preview), check logs for useful information, and contact support if the root cause appears to be a built-in FlutterFlow widget or action.

Who should use this

Builders who have added Custom Widgets, Custom Functions, or Custom Actions in their FlutterFlow project and observe a page or the app hang (freeze) without an error message.

What to collect before you start (only what you need for your troubleshooting)

Collect only the essentials below — the minimum you need to reproduce, test, and debug the issue yourself.

Exact reproduction steps
- The precise, step-by-step actions that cause the freeze (what you tap, in what order, what you enter). This lets you reproduce the issue reliably on the device/test build.
A minimal repro page you create
- A blank page in your project that contains only the custom widget or a single button that triggers the custom action/function. You’ll use this page to confirm the problem is in your custom code.
Run/test context (device + build) — test on device or test build, not Preview
- Which device (model), OS version, and whether you used TestFlight / Play internal / local debug build. Testing on a real device/test build is required because Preview can behave differently.
Device logs / console output
- The device log output captured while reproducing the freeze (adb logcat for Android, Xcode console for iOS, or other device console output). These logs are essential to see whether code executes, where it stops, or if any runtime messages appear.

Those four items are all you need to run the troubleshooting flow below on your own. If during the process you choose to inspect or edit your custom code, keep the single file or the block of code you are changing open so you can quickly comment/uncomment sections.

Step 1 — Create a minimal reproduction (first and most important step)

A minimal reproduction isolates whether the freeze comes from your custom code or something else.

In FlutterFlow, create a new blank page.
Add only the problematic Custom Widget, or place a single Button that triggers the Custom Action / Function.
Test on a device or test build (not Preview). If the freeze still appears on the minimal page, the issue is almost certainly in your custom code. If it does not appear, compare the minimal page with the full page to find differences.

Step 2 — Isolate by binary search (comment-out approach)

Narrow the fault quickly by removing or commenting code:

Comment out large blocks or remove subcalls inside your custom file.
Rebuild and run after each change. If the freeze disappears, re-enable smaller parts until the freeze returns.
Repeat until you identify the smallest block that triggers the freeze. This process commonly exposes infinite loops, heavy CPU work, or a single problematic async call.

Step 3 — Check the four usual causes (and how to fix each)

1) Infinite loops

Symptom: App becomes completely unresponsive with no error.
How to spot it: Repeated log output, or no progress beyond a particular print() log.
Fix: Ensure loops and recursion have valid termination conditions and bounds checks.

Bad example (infinite):

while (true) {   doHeavyWork(); }

Fixed example:

int attempts = 0; while (attempts < 1000) {   doHeavyWork();   attempts++; }

2) Unawaited `Future` / incorrect async handling

Symptom: Flows that wait for results never resume and the UI appears hung.
How to spot it: Missing await keywords, or actions that return before async work completes.
Fix: await asynchronous calls, add try/catch, and have Custom Actions return structured success/error results your Action Flow can check.

Pattern:

Future<Map<String, dynamic>> runTask(...) async {   try {     final result = await someAsyncWork();     return { 'success': true, 'data': result };   } catch (e) {     return { 'success': false, 'error': e.toString() };   } }

Then in the Action Flow, guard on the action output success with an If/Else branch.

3) Heavy synchronous CPU work on the UI thread

Symptom: UI stutters or freezes while heavy parsing or loops run.
How to spot it: Freeze correlates with large computations.
Fix: Offload heavy work to an isolate or break it into small asynchronous chunks so the event loop can run and the UI stays responsive.

Chunking example:

Future<void> processLargeList(List items) async {   for (var i = 0; i < items.length; i += 100) {     final end = (i + 100).clamp(0, items.length);     processBatch(items.sublist(i, end));     // yield briefly so UI can update     await Future.delayed(Duration(milliseconds: 1));   } }

4) Platform-specific code running on the wrong platform

Symptom: Works on web but freezes or fails on mobile.
Fix: Mark web-only custom actions as Web only in Custom Action settings or add platform conditionals so web code never executes on mobile.

For custom widgets, you can set the conditional visibility to only show if the platform is correct as shown in the screenshots below:

For the custom actions, you can set the conditions before calling an action:

Step 4 — Instrumentation: quick probes that reveal where execution stops

Use lightweight probes to see how far your code runs:

Insert print() statements at key points and observe device logs. If logs stop at the same line each time, that pinpoints the stall.
Try a temporary early return: make the function return immediately; if the freeze disappears, the problem is inside that function.
Test on device/test build and check device logs

You can learn more about how you can use print statements to investigate custom code in this article.

Step 6 — Verify your fix

After applying a fix:

Test the minimal repro page on device/test build and confirm the freeze is gone.
Re-test the original page and full app flows.

When to contact support

If you’ve completed the above and the freeze persists, or if you determine the freeze is caused by a built-in FlutterFlow widget or action, contact support and include:

A minimal repro project (blank page with only the test widget or a single button).
The custom code file you tested.
Device logs showing the freeze.
Exact reproduction steps and the run context (TestFlight / Play internal / local debug).
Screenshots or a short screen recording that demonstrates the freeze.

Providing these artifacts up front helps the team reproduce and resolve the issue more quickly.

Final notes

Always test on a device or a test build (not Preview). Device logs are the most reliable source of information.
If you confirm the freeze is caused by a built-in FlutterFlow widget or action, feel free to contact support — include the minimal repro, custom code, and device logs to speed up resolution.
The steps above are designed so you can find and fix the issue yourself in most cases. If you want, I can convert the Quick checklist into a one-click macro or provide a minimal repro template you can download and adapt.