Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Flutter web warns that webOnlyWarmupEngine and webOnlySetPluginHandler are deprecated

ErrorThe webOnlyWarmupEngine API is deprecated and will be removed in a future release.

Short answer

Flutter's web engine marks webOnlyWarmupEngine and webOnlySetPluginHandler in dart:ui as deprecated. Their replacements live in dart:ui_web: bootstrapEngine and setPluginHandler. The warning comes from code that still calls the old names, either your own web entry point or a plugin. Update the call or the plugin.

  • Applies to Flutter 3.35 web, Dart 3.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out whether the old names are in your code or inside a dependency.

    grep -rn "webOnlyWarmupEngine\|webOnlySetPluginHandler" lib web test
    grep -rln "webOnlyWarmupEngine\|webOnlySetPluginHandler" "$HOME/.pub-cache/hosted/pub.dev" | head
  2. 2Match what you see, then jump to its fix

    1. 1The first grep finds a match in lib/ or web/, usually in a custom web entry file.Your own code calls the old dart:ui functionsFix
    2. 2The second grep matches files in the pub cache and your own folders are clean.A package still calls the deprecated functionsFix

What does the error look like?

  • The webOnlyWarmupEngine API is deprecated and will be removed in a future release.
  • Please use `bootstrapEngine` from `dart:ui_web` instead.
  • The webOnlySetPluginHandler API is deprecated and will be removed in a future release.
  • Please use `setPluginHandler` from `dart:ui_web` instead.

Cause 1 of 2

Your own code calls the old dart:ui functions

1Check

The engine source states that both calls are deprecated and names the replacement from dart:ui_web in each message.

grep -rn "ui.webOnly\|webOnlyWarmupEngine\|webOnlySetPluginHandler" lib web

2Fix

Replace webOnlyWarmupEngine with bootstrapEngine from dart:ui_web. Its optional parameters are registerPlugins and runApp, so the plugin registrant and your main run through it. Replace webOnlySetPluginHandler with setPluginHandler from the same library.

import 'dart:ui_web' as ui_web;

Future<void> main() async {
  await ui_web.bootstrapEngine(
    registerPlugins: registerPlugins, // from web_plugin_registrant.dart
    runApp: () => app.main(),
  );
}

3Verify

Run the app in Chrome and check that the console no longer prints the deprecation text.

flutter run -d chrome

Confirmed by flutter.googlesource.com

Did this fix it?

Cause 2 of 2

A package still calls the deprecated functions

1Check

Find which package owns the file, then see whether a newer release exists.

grep -rln "webOnlyWarmupEngine\|webOnlySetPluginHandler" "$HOME/.pub-cache/hosted/pub.dev"
flutter pub outdated

2Fix

Upgrade that package to a release that uses dart:ui_web. If none exists, open an issue on its repository; the warning is harmless until the API is removed, but a removal will then break your web build.

flutter pub upgrade <package-name>

3Verify

Run the web build again and read the console for the same text.

flutter build web

Confirmed by api.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Run flutter pub outdated before every Flutter upgrade and move web plugins forward first.
  • Keep web/index.html and flutter_bootstrap.js on the documented loader instead of hand-written engine calls.
  • Do not call engine internals from app code; use the dart:ui_web APIs that the docs list.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.