Key Takeaway
Most FlutterFlow custom functions that "don't work" fail for one of five reasons: a missing or wrong return type, an argument that isn't passed or is the wrong type, unhandled null values, a package import that wasn't declared, or async code stuffed into a function that expects a synchronous result. Fix the signature first, handle nulls explicitly, and if you need to call an API or await something, use a custom action instead of a custom function.
Custom functions in FlutterFlow are small pieces of Dart you write to do work the visual builder can't express on its own: format a date, compute a total, transform a string. When they break, the error is rarely about your logic. It's almost always the contract between FlutterFlow and your Dart code: the return type, the arguments, or null handling. This guide walks through the common failures in order, with the actual fix for each, and shows where a custom action is the right tool instead.
Diagnose it fast: symptom, cause, fix
Before you dig into any single section, match what you're seeing against this table. As of 2026, these five failure modes account for the large majority of custom functions that compile fine but misbehave or won't build at all.
| Symptom | Likely cause | Fix |
|---|---|---|
| Build fails, or function returns nothing in test mode | Wrong or missing return type | Make the declared return type match every return; ensure every code path returns it |
| Function returns null or a default even though the logic is right | Unbound or mistyped argument | Bind every argument at each call site; match name, type, and nullability |
| Works in preview, crashes on a device | Unhandled null value | Mark the argument nullable, check for null, use ?? instead of ! |
| Build fails with an undefined-name error | Missing package import or dependency | Add the package to pub dependencies and the import line, with a compatible version |
| You get a future or null instead of your value | Async logic in a sync function | Move the work to a custom action, which is async and can await |
Start with the function signature
FlutterFlow generates a Dart function from the fields you fill in: a name, a list of arguments with types, and a return type. If any of those don't match what your code actually does, the project fails to compile and the function silently does nothing in test mode.
Set a return type that matches what you return
The most common cause of a custom function not working is a return type mismatch. If you set the return type to String but your code returns an int, or you set a return type and forget the return statement, the function won't compile. Check that:
- Every code path ends in a
returnof the declared type. - The declared return type matches reality (a price calculation returns
double, notString). - If the function only does work and gives nothing back, there is no "void" option for custom functions. That's a sign you actually want a custom action.
Pass every argument, with the right type
Each argument you define in the function panel has to be wired up wherever you call the function. A function that works in isolation but returns null or a default when called usually has an argument that was never bound, or was bound to a variable of the wrong type. Confirm the argument name, type, and whether you marked it nullable all match how you use it inside the body.
Handle nullable values explicitly
Dart is null-safe, and this trips up more FlutterFlow functions than anything else. If an argument can be null (an empty text field, a not-yet-loaded API value), your code has to say what happens then.
- Mark the argument nullable in the panel if it can be null, then check for null inside the body:
if (value == null) return ''; - Use the null-aware operators instead of forcing a value:
value?.toString() ?? 'default'rather thanvalue!.toString(). - Avoid the bang operator (
!) unless you are certain the value exists. A null check that fails at runtime is the classic "works in preview, crashes on device" bug.
Declare package imports and dependencies
If your function uses anything outside Dart's core (for example intl for date formatting or collection for list helpers), FlutterFlow needs to know about it in two places, or the build breaks with an undefined-name error.
- Add the package under the project's pub dependencies (the dependencies setting), not just an
importline. - Add the matching
importstatement in the function's code panel. - Pin a version that's compatible with your Flutter SDK. A version conflict shows up as a build failure, not a code error in the editor.
Async vs sync: the dividing line
This is the fix people miss most. Custom functions are synchronous. They take inputs and return a value immediately. They cannot await, call an API, read from a database, or do anything that takes time. If you try, you'll get a future or a null instead of your value.
When you need to wait for something, use a custom action instead. Actions are async, can await, can return values back into app state, and run inside the action flow rather than inline. Use this table to decide:
| You need to... | Use | Why |
|---|---|---|
| Format, calculate, or transform a value | Custom function | Synchronous, returns a value inline |
| Call an API or await a result | Custom action | Async, can use await |
| Read or write the database | Custom action | Needs an async context |
| Show a dialog or change app state | Custom action | Side effects belong in the action flow |
Debug with print and the right test surface
When a function compiles but gives the wrong answer, add print() statements inside the body and watch the debug console while you run the app in test mode or on a device. Print the inputs at the top and the value just before you return it. That single step tells you whether the problem is the data coming in or the logic in the middle.
- Test on a real device or in run mode, not just the canvas preview. Some null and platform issues only appear at runtime.
- If the editor flags an error, read the line number it gives. FlutterFlow surfaces Dart analyzer errors directly, and they are usually precise.
- For anything involving timing or async, the print output in the console will show you the order operations actually run in.
A quick checklist before you give up on a function
- Return type matches what every path returns.
- All arguments are bound, with matching types and nullability.
- Null cases are handled with
??or an explicit check, no stray!. - Any package is in both the dependencies and the import line.
- Nothing async lives in the function. Move it to a custom action.
- You've run it on a device with
print()tracing the inputs.
FAQ
Why does my FlutterFlow custom function return null?
Usually because an argument came in null and your code didn't handle it, or because the return type doesn't match what you return so FlutterFlow falls back to a default. Add a null check at the top, confirm every argument is bound when you call the function, and make sure the declared return type matches the value you actually return.
Can a custom function call an API in FlutterFlow?
No. Custom functions are synchronous and cannot await. Calling an API, reading a database, or doing anything that takes time has to go in a custom action, which is async and can return its result back into app state. If your function needs await, that is the signal to convert it to an action.
Why does my custom function work in preview but crash on a device?
Almost always a null safety issue. The canvas preview can pass placeholder data that happens to be non-null, while a real device hands you an empty or unset value. Replace any bang operator (!) with a null-aware check, and test on a physical device before you ship.
How do I add a package to a custom function?
Add the package to your project's pub dependencies with a compatible version, then add the matching import statement in the function's code panel. If you do only one of the two, the build fails with an undefined name or a missing dependency error.
When the maintenance is the real problem
Custom functions and actions are how you stretch a no-code builder past its limits. They also turn your app into a codebase someone has to keep working: Dart versions move, packages break, null bugs surface on new devices, and every fix means opening the builder again. That's fine if you enjoy it. It's a tax if you just want the app to run.
That's the gap Rehost fills. We're a done-for-you operator based in Los Angeles. We design, build, host, monitor, and operate your custom app and website, and your team never logs into a dashboard or debugs a function. Plans start at $950/mo billed by monthly active users, with no setup fee, and you own the app, the App Store and Google Play accounts, the domain, the code, and the data, all portable if you ever leave. A website ships in under a week and an app in about two weeks. See what Rehost actually is, the plans for teams, and the full pricing if you'd rather hand off the upkeep entirely.
The bottom line
FlutterFlow custom functions break for predictable reasons: a wrong return type, an unbound or mistyped argument, an unhandled null, a missing package, or async logic in a sync function. Work the checklist in that order and most issues resolve in minutes. And if the bigger problem is that you're maintaining the build at all, hand it off. Talk to Rehost and we'll build, host, and operate it so you never open the editor again.