FlutterFlow custom code errors: fixing widgets and actions

Most FlutterFlow custom code errors come from a short list: the name in the code doesn't match the name in the editor, an argument is defined differently in the settings and in the code, a package is missing its import or conflicts with another package, or a value has the wrong type or can be null. FlutterFlow's Compile Code button and its code analyzer show where the error is; regenerating the boilerplate and comparing it with your code fixes a large share of them.

This guide explains how the custom code types differ, then works through the common errors by symptom, and ends with habits that keep custom code from breaking the whole build.

What kinds of custom code does FlutterFlow have?

Each type has its own rules, and many errors come from treating one like another:

Two rules worth remembering: Custom Functions must compile for the app to run at all, and Custom Widgets need both width and height set, or they won't render correctly.

How do I find the actual error?

1. Open the custom code item and click Compile Code. The analyzer stops at the first compilation error and shows it.
2. Read the first error, not the last. Later errors are often side effects of the first one.
3. Check FlutterFlow's project issues for warnings about uncompiled widgets or actions.
4. For errors that only happen while the app runs, use the browser console in Run mode or the Debug Info panel in Test mode.

If the message inside FlutterFlow is vague, download the code and run it locally with the Flutter tools, or use FlutterFlow's VS Code extension. The local compiler usually names the exact file and line.

"Unknown error compiling custom code": what does it mean?

FlutterFlow users regularly report a generic message saying that a common cause is a custom widget or action whose name in the code doesn't match the name in the editor. Take it literally first:

• The function name of a Custom Action must match the action's name in FlutterFlow.
• The class name of a Custom Widget must match the widget's name in FlutterFlow.

The fastest fix is Add Boilerplate Code, which generates code with the correct names and argument list. Compare it with yours. On the desktop app, regenerating may replace everything in the file, so copy your code somewhere safe before you do it.

If the names match and the error remains, work through the sections below.

Why does FlutterFlow say an argument or type doesn't match?

The arguments you define in the settings panel and the parameters in the code must be identical: same names, same types, same order, and the same nullability. If an argument is optional (nullable) in the settings, declare it nullable in the code too (for example String? note), and handle the null case.

Other causes from FlutterFlow's custom action checklist:

• Return type mismatch. The function must return exactly the type set in the settings panel.
• Name conflicts. An action and one of its arguments can't share a name.
• Reserved words as names. Dart keywords such as in, as, enum, import, this or static can't be used as argument names.
• Single value vs list. Passing one item where a list is expected, or the reverse.
• Type conversions. A text field holding "42" isn't an int. Convert explicitly with int.tryParse, .toString() or .toDouble().
• Duplicate types. Don't redefine a data type that already exists in the schema panel. FlutterFlow generates your custom data types as classes named like ItemsStruct; use those.
• Callback types. A callback action passed into a widget must return the type the widget expects.

Why does my package import fail?

The import is missing or in the wrong place

FlutterFlow adds standard imports to every new action and widget, and you can't edit those. Your own imports go after the line that says "Do not remove or modify the code above". If you see something like "The method 'AnimatedText' isn't defined", the package is installed but not imported. Copy the exact import line from the package's Installing tab on pub.dev.

Custom Functions don't allow extra imports at all. If you need a package, make it a Custom Action instead.

The package isn't declared, or its version conflicts

Add the package under Settings and Integrations, Project Dependencies, Custom Dependencies, with Add Pub Dependency, and add it in the Pubspec Dependency section of the code file. FlutterFlow shows version conflicts as warnings in the Custom Dependencies tab and the code editor.

Conflicts happen when your package needs a different version of something FlutterFlow already uses, or when two of your packages disagree. Check the package's dependencies on pub.dev, try a version that matches what FlutterFlow ships, and add packages one at a time, compiling after each, so you know which one broke the build. Some packages need other packages imported as well; the pub.dev page lists them.

It works on the phone but not in Run or Test mode

Run and Test mode run your app on the web. FlutterFlow's docs say a package must support Web to work there. Camera, Bluetooth and some file packages don't. Test those on a device instead.

How do I stop one broken file from blocking the whole app?

Custom Widgets and Custom Actions have an Exclude from compilation toggle. Turning it on lets the rest of the project compile while you fix the broken item. FlutterFlow's docs also recommend it for code that imports FlutterFlow's internal files (paths like ../../flutterflow). Remember to turn it off and compile once the fix is in, or you'll ship without that code being checked.

How do I keep custom code from breaking again?

1. Start from the boilerplate every time, then add your logic.
2. Give widgets distinctive names. A widget called Map or Widget can clash with a package.
3. Keep custom code small. Put complex logic in one well-tested action rather than spread across many.
4. Handle nulls on purpose. Give every nullable input a fallback.
5. Write down why each package is there, so it's easy to decide what to drop when versions conflict.
6. Use a branch for big changes. FlutterFlow notes that switching to its new custom code layout can't be undone, so try it on a branch first.

For the wider picture of what breaks in generated code, see our guide on TypeScript and build errors in AI-generated code and how to report a bug to a developer so you get help faster.

Quick answers

Why does my FlutterFlow custom widget not show in the builder? Custom Widgets have to compile successfully before they preview, and they need both width and height set.

Why can't I import a package in a Custom Function? Custom Functions don't allow extra imports. Use a Custom Action or Custom Widget instead.

What does Exclude from compilation do? It skips that widget or action during compilation so the rest of the project can build. Turn it off again once fixed.

Why does my package work on a phone but not in Test mode? Test and Run mode run on the web, and the package has to support Web.

Still stuck on a compile error?

Some errors only make sense with the whole project in view. Our FlutterFlow app service can take over custom code, package conflicts and builds, and when the app is ready we help with publishing to the App Store. Send us the exact error message through the contact form.