Maaz Zindani

Loading the index…

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

Flutter form validation does nothing because the form key has no state

ErrorThe method 'validate' was called on null.

Short answer

validate() fails when the GlobalKey you call it on is not attached to a FormState. The key may never have been given to the Form, may have the wrong type, may be re-created on every read, or the Form may not be in the widget tree at that moment. Print currentState inside the button handler to find which.

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

Fix it fast

  1. 1Find out which cause you have

    Print the key's state inside the handler that calls validate(). If it prints null, the key is not attached to a Form that is in the tree right now. If it prints an instance of FormState, the key is fine and the cause is not on this page.

    onPressed: () {
      debugPrint('form state: ${_formKey.currentState}');
      if (_formKey.currentState!.validate()) {
        // save the form
      }
    },
  2. 2Match what you see, then jump to its fix

    1. 1currentState is null every time, even when the form is fully on screen; the key is declared but not passed onThe Form was never given the keyFix
    2. 2The key is passed to the Form, yet currentState is still null; the declaration reads GlobalKey<_MyFormState> or another State classThe key is typed with the wrong State classFix
    3. 3The key lives in a getter, a StatelessWidget or inside build(); typed text vanishes on rebuilds, or validate() finds no stateA new GlobalKey is created every time it is read or builtFix
    4. 4The key is correct but currentState is null on one screen, tab or step only; the Form sits in a branch that is not built at that momentThe Form is not in the widget tree when validate() runsFix
    5. 5Form.of() was called with a context that does not contain a Form widgetForm.of(context) uses a context that sits above the FormFix

What does the error look like?

  • The method 'validate' was called on null.
  • Form.of() was called with a context that does not contain a Form widget.
  • TextFormField validator not working

Cause 1 of 5

The Form was never given the key

1Check

Look at the Form constructor. The key must be passed as the Form's own key argument, not to the Column, the TextFormField or the button.

grep -rn -B2 -A4 "Form(" lib/

2Fix

Pass the key to the Form itself. Calling validate() then reaches the FormState that Flutter creates for that Form.

return Form(
  key: _formKey,
  child: Column(
    children: [
      TextFormField(
        validator: (value) =>
            (value == null || value.isEmpty) ? 'Please enter some text' : null,
      ),
    ],
  ),
);

3Verify

Run the app, tap the button and read the printed value: it is now a FormState, and empty fields show their error text.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

Cause 2 of 5

The key is typed with the wrong State class

1Check

Read the type argument of the GlobalKey. A GlobalKey returns a state only when the widget's State object is a subtype of that type argument. The State behind a Form is FormState, not your own State class.

grep -rn "GlobalKey<" lib/

2Fix

Declare the key as GlobalKey<FormState>.

class _MyCustomFormState extends State<MyCustomForm> {
  // FormState, not _MyCustomFormState
  final _formKey = GlobalKey<FormState>();
}

3Verify

Hot restart and tap the button again. The printed value is now a FormState.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 3 of 5

A new GlobalKey is created every time it is read or built

1Check

Find where the key is created. Anything other than a field that is initialised once in a State object makes a different key on each build or read.

grep -rn "GlobalKey<FormState>" lib/

2Fix

Create the key once, as a field of the State object (or in initState), and use that same field for the Form and for validate().

// wrong: a new key on every read
// GlobalKey<FormState> get _formKey => GlobalKey<FormState>();

// right: one key for the life of the State object
final _formKey = GlobalKey<FormState>();

3Verify

Type into a field, trigger a rebuild (for example with setState elsewhere) and confirm the text stays.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 4 of 5

The Form is not in the widget tree when validate() runs

1Check

Find the widget that builds the Form and ask whether it can be absent when the button is pressed, for example a branch of an if that is currently false, or a page that has not been built yet. A key returns null when no widget in the tree has it.

grep -rn "_formKey" lib/

2Fix

Validate only a form that is on screen, or move the Form (and its key) up to a widget that stays built, so the button and the Form are in the same tree.

// one Form around everything the button validates
Form(
  key: _formKey,
  child: Column(children: [ /* fields */ ]),
)

3Verify

Press the button from every screen that has the form. The printed state is a FormState each time.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 5 of 5

Form.of(context) uses a context that sits above the Form

1Check

Form.of looks upwards from the context you give it. If you call it with the context of the widget that builds the Form, the Form is below that context, not above it.

grep -rn "Form.of(" lib/

2Fix

Call it from a context beneath the Form, for example inside a Builder, or use the Form's GlobalKey instead. Form.maybeOf returns null instead of throwing if you want to handle the missing case.

Form(
  child: Builder(
    builder: (context) => ElevatedButton(
      onPressed: () => Form.of(context).validate(),
      child: const Text('Submit'),
    ),
  ),
)

3Verify

Tap the button. The error text appears under the invalid fields and no exception is thrown.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Declare the key as final _formKey = GlobalKey<FormState>(); in the State object and pass it to Form(key: _formKey) in the same commit.
  • Never create a GlobalKey inside build() or in a getter.
  • Do not call currentState! without thought. Print or assert it once while wiring the form up.
  • Keep one Form around the fields one button validates, so the key and the button live in the same tree.

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.