Flutter web works locally but the live site says _flutter is not defined
_flutter is undefinedShort 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.
Fix it fast
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 2002Match what you see, then jump to its fix
- 1
The 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
A script URL answers 200 with content type text/html instead of JavaScript.The server answers the script request with index.htmlFix - 3
The 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
- 1
What does the error look like?
_flutter is undefinedWarning: 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.js2Fix
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.jsConfirmed by docs.flutter.dev
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 web3Verify
Each script URL now answers 200 with a JavaScript content type.
curl -sI https://example.com/flutter_bootstrap.js | grep -i content-typeConfirmed by docs.flutter.dev
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-control2Fix
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-cache3Verify
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-controlConfirmed by docs.flutter.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
Flutter web request fails with a CORS error and Dart code cannot fix it
CORS preflight channel did not succeed
In a browser, the browser decides whether your Dart code may read a cross-origin response, and the server grants that with CORS headers.
4 causes, each with a fixMobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fixMobile apps
Dart throws ConcurrentModificationError while looping over a list
ConcurrentModificationError
Dart throws this when a collection changes size while something iterates it.
2 causes, each with a fix