Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter web works locally but the live site says _flutter is not defined

Error_flutter is undefined

Short answer

The browser console error _flutter is undefined means the script that creates the _flutter loader object never ran. That happens when a custom index.html or flutter_bootstrap.js uses _flutter without the {{flutter_js}} token, when the server returns your index.html instead of the script file, or when a stale cached index.html points to old files.

  • Applies to Flutter 3.3x stable, Dart 3.x, flutter build web
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the live server for the bootstrap script and look at the first line and the content type. A real script starts with JavaScript, not with <!DOCTYPE html>.

    curl -sI https://example.com/flutter_bootstrap.js | head -n 5
    curl -s https://example.com/flutter_bootstrap.js | head -c 200
  2. 2Match what you see, then jump to its fix

    1. 1The error appears on the first line that touches _flutter, in your own web/index.html or web/flutter_bootstrap.js.A custom script uses _flutter without the {{flutter_js}} tokenFix
    2. 2A script URL answers 200 with content type text/html instead of JavaScript.The server answers the script request with index.htmlFix
    3. 3The error is gone in a private window or after a hard refresh, and comes back for returning visitors.A cached index.html points at files from an older buildFix

What does the error look like?

  • _flutter is undefined
  • Warning: In index.html:40: "FlutterLoader.loadEntrypoint" is deprecated. Use "FlutterLoader.load" instead.

Cause 1 of 3

A custom script uses _flutter without the {{flutter_js}} token

1Check

Open the file in the web folder. The Flutter docs say _flutter.loader is made available by the {{flutter_js}} token, so any script that calls it must contain that token first.

grep -n "_flutter\|flutter_js\|flutter_build_config" web/index.html web/flutter_bootstrap.js

2Fix

A custom bootstrap script needs three parts: the {{flutter_js}} token, the {{flutter_build_config}} token, and a call to _flutter.loader.load(). Or delete the custom file and use the generated one.

{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load();

3Verify

Rebuild and open build/web/flutter_bootstrap.js. The tokens are replaced by real code, and the app starts.

flutter build web && head -c 300 build/web/flutter_bootstrap.js

Confirmed by docs.flutter.dev

Did this fix it?

Cause 2 of 3

The server answers the script request with index.html

1Check

A single-page-app rule that sends every unknown path to /index.html also catches the JavaScript files if the path is wrong or the file was not uploaded. The Flutter deployment page says missing assets should return a genuine 404, not 200 text/html.

curl -sI https://example.com/flutter.js | grep -i "^HTTP\|content-type"
curl -sI https://example.com/main.dart.js | grep -i "^HTTP\|content-type"

2Fix

Upload the whole build/web folder, not only index.html. In the rewrite rules, leave out /assets, /canvaskit, /icons and /main.dart.* so a missing file returns a real 404 and you can see what is absent.

flutter build web

3Verify

Each script URL now answers 200 with a JavaScript content type.

curl -sI https://example.com/flutter_bootstrap.js | grep -i content-type

Confirmed by docs.flutter.dev

Did this fix it?

Cause 3 of 3

A cached index.html points at files from an older build

1Check

The deployment page says index.html, flutter_bootstrap.js and flutter.js are unhashed files that should be served with no-cache or max-age=0, must-revalidate. Check what your server sends.

curl -sI https://example.com/ | grep -i cache-control
curl -sI https://example.com/flutter_bootstrap.js | grep -i cache-control

2Fix

Serve those unhashed files with Cache-Control: no-cache, and upload index.html and flutter_bootstrap.js last so visitors never get a new page with old scripts.

# In your host or CDN settings, send this header for
# index.html, flutter_bootstrap.js and flutter.js:
Cache-Control: no-cache

3Verify

The response headers show no-cache, and a returning visitor loads the new build.

curl -sI https://example.com/flutter_bootstrap.js | grep -i cache-control

Confirmed by docs.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Start from the generated web/index.html and change as little as you can; use the script tag for flutter_bootstrap.js.
  • Run the first-step curl against the live URL after every deploy.
  • Upload the whole build/web folder as one unit, with index.html last.
  • Set no-cache on index.html, flutter_bootstrap.js and flutter.js.

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

Next step

Want this handled for good?

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