A package that compiles on your laptop isn't automatically a package FlutterFlow will build. If a dependency is failing right now, open its pub.dev page and look at the platform row before you touch your widget code, because the missing piece is usually there and not in your Dart.
Across eight marketplace templates and more than forty custom widgets, the question I ask before designing a widget is whether the dependency it needs will survive FlutterFlow's cloud build, not whether the widget can be written. The case study records the constraint plainly: pub package limits are real, and some packages that work in plain Flutter break inside FlutterFlow's build. If the vocabulary is new, what Flutter actually is is the shorter prerequisite.
Why is your FlutterFlow custom code package not working?
Usually because the package needs something the cloud build can't provide: web support for Run/Test Mode, native platform code you can't edit, or a version that conflicts with what FlutterFlow already depends on.
Notice what's absent from that list. Your widget code. What fails is dependency resolution, and the error names packages you didn't add in versions you didn't choose.
FlutterFlow's custom code documentation puts platform support first when choosing a package from pub.dev: "WEB: It must support Web to run your app in our Run/Test Mode." That is a prerequisite for the editor's own preview, so a package can be well maintained, popular on mobile and still unusable here. The same page warns: "The current dependency might depend on other dependencies to work. So make sure you also copy the name and version of all the additional dependencies." Transitive dependencies are where the surprises live.
How do pubspec dependencies work in FlutterFlow?
You hand FlutterFlow a package name and a version in one of two places, and the build has to resolve them against everything else the project depends on.
According to the same documentation, there are two routes. Globally, go to Settings and Integrations, then Project Dependencies, then the Custom Dependencies tab, and click Add Pub Dependency with the name and version. Locally, paste the Pubspec Dependency into the bottom-right panel of a custom code file and add the import after the default imports.
Pub's version solver still has to find one version of every package that satisfies all constraints at once. I can't inspect FlutterFlow's generated pubspec from here, so treat that as how pub works generally, not a description of FlutterFlow's internals. What FlutterFlow does document is the shared-dependency rule for imported libraries: "if the project and the library share the same dependency, the version must match exactly to avoid conflicts" (Libraries documentation). Exactly, not compatibly, which is narrower than the caret ranges you'd write by hand.
Why do pure-Dart packages fit and native plugins don't?
A pure-Dart package is source that compiles with your widget, while a plugin carries platform-specific code, and FlutterFlow doesn't let you edit that native side in its web UI.
Flutter's own package documentation defines plugin packages as "an API written in Dart code combined with one or more platform-specific implementations", which can be written in Kotlin, Java, Swift or Objective-C. FlutterFlow's MethodChannels guide states that the platform "does not allow direct editing of platform-native code (Kotlin, Swift) through its web UI". The documented workflow for native needs is to create a Flutter plugin outside FlutterFlow, publish the repository to GitHub, and add its Git URL as a dependency in the Custom Code settings.
Read that as a cost. Once a package needs native code you control, the dependency becomes a repository you maintain and keep compiling against whatever Flutter version the platform runs. That's a fair trade for a vendor SDK with no alternative and a poor one for a date picker. This is my recommendation, not a documented rule.
Does the cloud builder pin versions you didn't choose?
Evidence from public reports says it can. A community thread on dependency constraints in the Cloud Builder reports that a data-sync package's version 2 line needs newer foundational dependencies than those "globally pinned within the Cloud Builder environment", and that exporting the code and bumping versions locally resolved it.
A second report involves a package the author never added. A FlutterFlow issue opened on 9 September 2026, labelled "status: confirmed" and still open when I checked on 30 September, describes a web deployment failing after enabling Web Push Notifications:
"Because digi_market depends on cloud_functions_web 4.11.2 which depends on web ^1.1.1, web ^1.1.1 is required. So, because digi_market depends on web 1.1.0, version solving failed."
The reporter couldn't find where web 1.1.0 came from in the custom or FlutterFlow dependency lists. This suggests that enabling a platform feature can change your dependency graph without any package appearing in your list, which is why you can't always tell which half of the pubspec is yours.
Which packages are safe inside a FlutterFlow custom widget?
Packages that are pure Dart, declare web support next to mobile, and carry few transitive dependencies are the lowest-risk candidates. No table can promise a build, so this sorts risk and points to the documented behaviour.
| Package shape | What to check | What the docs say | What to do |
|---|---|---|---|
| Pure Dart, no platform code | Transitive dependency list | Copy every additional dependency's name and version | Try it first, then run the project |
| UI-only package with web support | Web chip on pub.dev | Web support is required for Run/Test Mode | Try it first, then run the project |
| Plugin with Android or iOS code | Whether you'd have to touch native files | Native code can't be edited in the web UI | Wrap it in your own Flutter plugin and add it by Git URL |
| Package without web support | Platform row on pub.dev | Web support is required for Run/Test Mode | Find a web-capable alternative |
| Package that conflicts with a shared dependency | Version solving errors | Shared library dependencies must match exactly | Pin an older version, or choose a different package |
The plugin row costs the most in template work, because everything in a marketplace template has to work in FlutterFlow's cloud build and each template ships as one package of widgets, instructions, docs and images. One unresolvable dependency holds up the whole submission.
What is a five-minute dependency check?
Run this on the pub.dev page, before any widget code exists:
- Read the platform chips. pub.dev's scoring documentation says "The platform support will be detected by analyzing the transitive import graph of the top-level libraries, and finding what core libraries are used." If Web is missing, FlutterFlow's Run/Test Mode requirement is unmet.
- Open the Installing tab and count the dependencies. Every transitive package is another constraint, and FlutterFlow tells you to copy them all.
- Check whether the package is a plugin. Look for Android and iOS implementations in its repository. If they exist, price the Git-URL route.
- Look at the last publish date. FlutterFlow's docs say "A regularly updated package is more likely compatible with the latest Dart/Flutter versions and has fewer bugs."
- Read Pub Points as a filter. FlutterFlow describes them as telling "the quality of the dependency (out of 130) based on code style, platform support, and maintainability."
- Add it to a throwaway project and run it. This is the only step that is actual proof, and it costs less than discovering the conflict after the widget is wired into four screens.
Steps one to three remove most bad candidates. Step six is the one people skip.
What if the build has already failed?
Work backwards from the change that broke it. This order is my recommendation and not documented FlutterFlow behaviour:
- Remove the last dependency you added and rebuild. If the build turns green, the conflict is between that package and something the platform already holds.
- Read the version solving error for the package it says is required, then check whether that name appears in your custom dependency list at all. If it doesn't, suspect a platform feature or a transitive dependency.
- Try an older major version of your package, or a different package with the same job.
- If none of that works and the package is essential, compare it against the Git-URL plugin route before you spend more time on the pubspec.
What changed with Flutter 3.38.5?
FlutterFlow upgraded to Flutter 3.38.5 on Tuesday 3 February 2026. The upgrade announcement mentions "updates to dozens of third-party packages used across FlutterFlow" and says "you may need to make changes to custom code or dependencies." Platform upgrades aren't neutral for custom code, so re-run step six on any widget whose dependency you pinned before a platform upgrade.
If the widget doesn't belong in FlutterFlow at all, when to drop out of FlutterFlow into pure Flutter is the next decision. If you're still choosing a platform, my notes on which no-code tools hit a ceiling cover it, and FlutterFlow with Firebase and Stripe is the stack page.
Open the pub.dev page for the dependency you've already half-decided on and read the platform row. Does Web appear?