LateInitializationError in Flutter: Causes, Fixes and Release Builds
LateInitializationError means a late variable was read before it was set. Five causes with tested fixes, and why release web builds hide the field name.
LateInitializationError: Field '_x' has not been initialized means your code read a late variable before anything assigned it. The late keyword tells Dart "trust me, this will have a value before anyone reads it", and Dart checks that promise at runtime instead of at compile time. When the promise is broken, the read throws. The sibling message, has already been initialized, means a late final variable was assigned a second time.
The fix is to decide when the value really exists. Arrives asynchronously? Make the field nullable and show a loading state, or keep the Future and use FutureBuilder. Set on only one code path? Make it nullable. Assigned in a method that runs more than once? Drop final or assign it in initState().
We reproduced four of the five causes below on Flutter 3.47.8 (Dart 3.13.7) with widget tests, then built a broken screen for the web in release mode, where the error no longer names the field.
Tested on: Flutter 3.47.8 and Dart 3.13.7 with the default flutter_lints rules, on 29 October 2026. Widget tests for causes 1 to 4 and every fix (11/11 pass), a plain Dart program on the VM, AOT, dart2js and dart2wasm, and release web builds (JavaScript and Wasm) in headless Chromium. Cause 5 comes from the Flutter docs. No device runs.
What the error messages mean
Dart has three variants, and the wording tells you which mistake you made:
Field '_name' has not been initialized.: Alatefield or top-level variable was read before it was assigned.Local 'name' has not been initialized.: Same, for alatelocal variable (common in tests).Field '_name' has already been initialized.: Alate finalvariable was assigned twice.
Two details trip people up. First, private names carry a library suffix in debug output, so you'll see Field '_greeting@23438455' rather than _greeting; search your code for the part before the @. Second, late with an initializer (late final x = compute();) is lazy: the initializer runs on first read, and only once. Dart's variables guide describes both uses of late, and Understanding null safety explains the runtime check that throws.
The analyzer can't help here. Our lab project, with every broken example below, passed flutter analyze with the default flutter_lints rules and reported no issues. late is an explicit opt-out of the definite-assignment check, so the mistakes only show up when the code runs.
Five causes and how to fix each
Cause 1: an async value read in the first build
This is the most common version in Flutter apps. A field is filled by a Future, often SharedPreferences.getInstance(), a database open or an HTTP call, but build() runs before the Future completes.
class _GreetingState extends State<Greeting> {
late String _greeting; @override
void initState() {
super.initState();
loadGreeting().then((value) => setState(() => _greeting = value));
}
@override
Widget build(BuildContext context) => Text(_greeting); // throws on frame 1
}
initState() starts the load, returns immediately, and Flutter calls build() straight away. In our widget test the first frame threw LateInitializationError: Field '_greeting@23438455' has not been initialized.
Fix A: nullable field plus a loading state. This is the most honest model: there really is a moment with no value.
class _GreetingState extends State<Greeting> {
String? _greeting; @override
void initState() {
super.initState();
loadGreeting().then((value) {
if (!mounted) return;
setState(() => _greeting = value);
});
}
@override
Widget build(BuildContext context) {
final greeting = _greeting;
if (greeting == null) return const CircularProgressIndicator();
return Text(greeting);
}
}
The mounted check stops a late setState() if the user leaves the screen before the load finishes.
Fix B: keep the Future and let FutureBuilder wait. Here late final is correct, because the Future itself is assigned synchronously in initState(), before the first build.
class _GreetingState extends State<Greeting> {
late final Future<String> _greeting; @override
void initState() {
super.initState();
_greeting = loadGreeting(); // assigned before build() runs
}
@override
Widget build(BuildContext context) {
return FutureBuilder<String>(
future: _greeting,
builder: (context, snapshot) {
if (snapshot.hasError) return const Text('Could not load');
if (!snapshot.hasData) return const CircularProgressIndicator();
return Text(snapshot.data!);
},
);
}
}
Don't create the Future inside build(): every rebuild would start a new load. Both fixes passed their tests with no exception: a spinner on frame 1, the text after the load.
If the value comes from app-wide state rather than one screen, a state management layer that exposes a loading state does the same job; our Flutter state management guide compares the options.
Cause 2: a late final assigned in a method that runs twice
late final can be assigned exactly once. That's easy to get wrong in didChangeDependencies() or build(), which Flutter calls many times.
class _GridState extends State<Grid> {
late final double _columns; @override
void didChangeDependencies() {
super.didChangeDependencies();
_columns = MediaQuery.sizeOf(context).width > 600 ? 3 : 1;
}
// ...
}
The first frame is fine. Then the user rotates the phone, resizes a window or changes the text size, MediaQuery changes, didChangeDependencies() runs again, and the second assignment throws. In our test we changed the test view from 400 to 900 px wide and got Field '_columns@23438455' has already been initialized., followed by a second framework error, buildScope missed some dirty elements.
Fix: if the value depends on inherited data, it isn't final. Use plain late (or a non-late field with a default) and reassign it each time. Better still, compute layout values in build() from MediaQuery.sizeOf(context) so there's no stored copy to go stale. Our responsive layout guide covers that pattern. Use late final only for things you assign once in initState().
Cause 3: a field assigned on only one branch
The error doesn't have to come from build(). This one throws when the widget is removed:
late AnimationController _controller;@override
void initState() {
super.initState();
if (widget.animate) {
_controller = AnimationController(vsync: this, duration: const Duration(seconds: 1))
..repeat();
}
}
@override
void dispose() {
_controller.dispose(); // throws when animate was false
super.dispose();
}
With animate: false the screen works perfectly until you navigate away, and then dispose() reads the field that was never set: Field '_controller@23438455' has not been initialized. It's easy to miss because nothing looks wrong on screen.
Fix: when a value might legitimately not exist, the type should say so.
AnimationController? _controller;@override
void dispose() {
_controller?.dispose();
super.dispose();
}
The same applies to anything created inside an if, a switch or a try block. If you find yourself writing late for a field that's only sometimes set, use a nullable type instead.
Cause 4: a late variable in tests used outside its setUp
Test files often declare late Repo repo; at the top of main() and assign it in a setUp() inside one group. A test in a different group that has no setUp of its own reads the variable before anything assigned it:
void main() {
late Repo repo; group('no setUp here', () {
test('reads repo', () {
repo.items.length; // Local 'repo' has not been initialized.
});
});
group('with setUp', () {
setUp(() => repo = Repo());
test('adds an item', () { /* ... */ });
});
}
We hit an extra trap while writing this test: when the group with setUp ran first, the test in the other group passed, because it quietly reused the object left over from the earlier test. Test order hid the bug. Put setUp at the top level of main() when every group needs the value, so each test gets a fresh one. Our guide to widget tests for AI-generated Flutter code has more on keeping test setup honest.
Cause 5: a field you added during hot reload
If you add a late field and assign it in initState() while the app is running, a hot reload won't assign it. The hot reload docs say hot reload "doesn't rerun main() or initState()", so existing State objects keep their old state and the new field stays unset. Do a hot restart before you treat this as a real bug. (We took this from the docs; it's the one cause on this page we didn't reproduce.)
Related bug: late initializers run once
A lazy initializer that reads widget doesn't update when the parent passes new values:
class _TitleState extends State<TitleText> {
late final String _upper = widget.title.toUpperCase(); // runs once @override
Widget build(BuildContext context) => Text(_upper);
}
In our test the parent rebuilt TitleText with title: 'final', and the screen still showed DRAFT. Nothing throws. Derive values from widget inside build(), or update them in didUpdateWidget().
What the error looks like in a release web build
Debug builds tell you the field name. Release web builds don't.
We built the Cause 1 screen with flutter build web --release and opened it in headless Chromium at 393 × 852 with a 4-second load. In the JavaScript build the console showed:
LateInitializationError: Field '' has not been initialized.
The field name is empty. flutter build web passed -O4 to dart2js (we checked with -v), and from -O2 up dart2js adds --omit-late-names, which strips the names to save bytes; the help text for dart compile js lists this. The Wasm build (--wasm) went further:
LateInitializationError: Field has not been initialized (details omitted due to --omit-error-details)
[MEDIA PENDING UPLOAD: late-release-web-pair.png] Two phone-size captures of the same release web build: during a 4-second load the greeting card is a grey box, after the load it shows "Welcome back"
On screen the user saw a grey box where the card should be. Then the load finished, setState() rebuilt the widget, and the card appeared as if nothing had happened. The error was logged once, without a name. With a fast connection the grey box lasts a few milliseconds, so this kind of bug can ship unnoticed and only show up for users on slow networks.
To compare, we compiled a small Dart program that hits all three variants:
- Dart VM, AOT executable:
Field 'name' has not been initialized. - AOT with
--obfuscate: Some names replaced, e.g.Local 'qg' has not been initialized. - dart2js
-O1: Full names - dart2js
-O2,-O3,-O4:Field ''/Local '' - dart2wasm
-O2: No name, "details omitted"
How to find the field when the name is gone: reproduce in a debug or profile build, where names are kept. For production web reports, keep source maps (flutter build web --source-maps) private and use them to map the stack trace back to your file. With --obfuscate on mobile, keep the symbols from --split-debug-info so you can run flutter symbolize.
A checklist before you reach for late
- Async value? Nullable field plus a loading state, or
late final FutureplusFutureBuilder. - Only sometimes set? Nullable type, and
?.indispose(). - Assigned in
build()ordidChangeDependencies()? Notfinal, or compute it inbuild(). - Depends on
widget? Compute it inbuild(), not in a lazy initializer. - Expensive and always needed later?
late final x = compute();is a good fit; this is what lazylateis for. - Test variable? Assign it in a
setUp()that covers every test that reads it.
FAQ
Is late bad practice in Flutter?
late bad practice in Flutter?No. It's the right tool for values assigned once in initState() before the first build (controllers, focus nodes, a stored Future) and for expensive values you want computed lazily. It's the wrong tool for values that may not exist yet.
Should I just replace late with !?
late with !?That swaps one runtime error for another (Null check operator used on a null value). Make the field nullable only if you also handle the null case, for example with a loading widget.
Can I check whether a late variable is initialized?
No. Dart has no API to ask whether a late variable has a value. If you need to ask, the variable should be nullable.
Next step
Trace the field name (search for the part before the @), decide which of the five causes you have, then apply the matching fix and add a widget test that pumps the first frame. If you're building with an AI Flutter app builder, the same check applies to the generated code: async loads read in the first build are a pattern worth searching for before you ship.

