Maaz Zindani

Loading the index…

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

MUI Autocomplete warns that the value matches no option

ErrorMUI: The value provided to Autocomplete is invalid.

Short answer

Autocomplete compares its value with the options using strict equality. It warns when the value is not one of the option objects, for example a fresh object from your form state or an id such as 0. Pass the matching option, add isOptionEqualToValue to compare by id, and treat typed text separately if freeSolo is on.

  • Applies to MUI Material current stable, React 19, react-hook-form 7.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the value and the options side by side. The warning names the value it could not find. See whether it is an id, a text string or an object that merely looks like one of the options.

    console.log('value', value);
    console.log('options', options);
  2. 2Match what you see, then jump to its fix

    1. 1The value is an object you can find in the options by its id, yet the warning staysThe value is an object, but not the same object as an optionFix
    2. 2The warning names a number or an empty string, as in None of the options match with `0`The value is a bare id or a placeholder like 0, not an optionFix
    3. 3The warning appears after the user types a value that is not in the listfreeSolo lets users type text, but the options are objectsFix

What does the error look like?

  • MUI: The value provided to Autocomplete is invalid.
  • None of the options match with `0`

Cause 1 of 3

The value is an object, but not the same object as an option

1Check

Without isOptionEqualToValue, the value must have reference equality with an option. Values rebuilt from an API response, from form defaults or from JSON.parse are new objects, so they never equal the options.

console.log(options.includes(value), options.some(o => o.id === value?.id))

2Fix

Tell Autocomplete how to compare. Match on a stable field such as id.

<Autocomplete
  options={options}
  value={value}
  getOptionLabel={(o) => o.name}
  isOptionEqualToValue={(option, val) => option.id === val.id}
  onChange={(_, next) => setValue(next)}
/>

3Verify

The warning no longer shows in the console and the saved choice appears in the input when the form loads.

console.log(options.some(o => o.id === value?.id))

Confirmed by mui.com

Did this fix it?

Cause 2 of 3

The value is a bare id or a placeholder like 0, not an option

1Check

The value prop is the option itself, not its id. A form default of 0 can never reference any item in the list.

console.log(typeof value, options.find(o => o.id === value))

2Fix

Keep the whole option in state, or turn the id into its option before you pass it.

const selected = options.find((o) => o.id === form.categoryId) ?? null;

<Autocomplete
  options={options}
  value={selected}
  getOptionLabel={(o) => o.name}
  onChange={(_, next) => setForm({ ...form, categoryId: next?.id })}
/>

3Verify

Load the form with an existing id and with none. Neither case prints the warning.

console.log(selected)

Confirmed by mui.com

Did this fix it?

Cause 3 of 3

freeSolo lets users type text, but the options are objects

1Check

With freeSolo, the value created by typing is always a string, whatever the type of the options. MUI warns that non-string options can then cause a type mismatch.

grep -rn "freeSolo" src/

2Fix

Either turn freeSolo off so only listed options are valid, or keep strings and objects apart in your onChange handler.

<Autocomplete
  freeSolo
  options={options}
  getOptionLabel={(o) => (typeof o === 'string' ? o : o.name)}
  onChange={(_, next) =>
    typeof next === 'string' ? setCustom(next) : setValue(next)
  }
/>

3Verify

Type a new word and pick a listed option. Both paths work without a console warning.

console.log(typeof next)

Confirmed by mui.com

Did this fix it?

How do I stop it coming back?

  • Store the selected option, or look it up by id every render, instead of keeping a copy of it.
  • Always set isOptionEqualToValue when options come from an API.
  • Keep value referentially stable: MUI says its reference should change only when the value itself changes.

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.