angular/components · error · Error

Listbox cannot have more than one selected value in single s

Error message

Listbox cannot have more than one selected value in single selection mode.

What it means

CdkListbox validates its selection model via _verifyOptionValues. In single-selection mode (multiple=false) more than one selected value is invalid, so the listbox throws. This protects the single-select invariant that the selection model should hold at most one value.

Source

Thrown at src/cdk/listbox/listbox.ts:1021

            console.warn(`Found multiple CdkOption with the same value`, {
              option1: option.element,
              option2: duplicate.element,
            });
          }
          return;
        }
      }
    });
  }

  /** Verifies that the option values are valid. */
  private _verifyOptionValues() {
    if (this.options && (typeof ngDevMode === 'undefined' || ngDevMode)) {
      const selected = this.selectionModel.selected;
      const invalidValues = this._getInvalidOptionValues(selected);

      if (!this.multiple && selected.length > 1) {
        throw Error('Listbox cannot have more than one selected value in single selection mode.');
      }

      if (invalidValues.length) {
        throw Error('Listbox has selected values that do not match any of its options.');
      }
    }
  }

  /**
   * Coerces a value into an array representing a listbox selection.
   * @param value The value to coerce
   * @return An array
   */
  private _coerceValue(value: readonly T[]) {
    return value == null ? [] : coerceArray(value);
  }

  /**

View on GitHub (pinned to 0411926e7d)

Solutions

Pass a single value, not an array: `value: 'one'` instead of `value: ['one','two']` when multiple is false.
Set `multiple` to true if users must select several values.
Before toggling multiple -> false, reset the selection to at most one value (e.g. `listbox.value = undefined` or patch the control).
Fix the data source so only one initial value is selected for single mode.

Example fix

// before
this.listbox.value = ['a', 'b']; // multiple === false
// after
this.listbox.value = 'a'; // or set multiple = true for arrays

Defensive patterns

Strategy: validation

Validate before calling

const value = control.value;
const safe = Array.isArray(value) ? value[0] : value;
if (!listbox.multiple && Array.isArray(value)) {
  control.setValue(safe);
}

Type guard

function isSingleSelectionValue(v: unknown): v is string | number | undefined {
  return v === undefined || typeof v === 'string' || typeof v === 'number';
}

Try / catch

try {
  listbox.value = candidate;
} catch (e) {
  if ((e as Error).message.includes('more than one selected value')) {
    listbox.value = Array.isArray(candidate) ? candidate[0] : candidate;
  } else { throw e; }
}

Prevention

Match the value shape to the multiple input: scalar for single, array for multiple.
Reset selection before toggling multiple at runtime.
Type the control value (e.g. FormControl<string>) to prevent arrays leaking in.
Add unit tests covering both single and multi configurations.

When it happens

Trigger: Binding [value] / form-control value to an array with more than one entry while `multiple` is false; changing multiple from true to false at runtime while several options remain selected.

Common situations: Reusing the same form control definition for both single and multi select variants; a checkbox-group-like template accidentally bound to a single-select listbox; toggling the `multiple` input without resetting the selection.

Related errors

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/39163e098c982589. Report an issue: GitHub.