material-components/material-components-android · error · IllegalArgumentException

> boxBackgroundMode < is illegal; only @BoxBackgroundMode co

Error message

> boxBackgroundMode < is illegal; only @BoxBackgroundMode constants are supported.

What it means

TextInputLayout's box-background setup switches over the @BoxBackgroundMode IntDef constants (FILLED, OUTLINE, NONE) to build the matching MaterialShapeDrawable underline/background. Any other int reaches default and throws IllegalArgumentException stating only BoxBackgroundMode constants are supported.

Source

Thrown at lib/java/com/google/android/material/textfield/TextInputLayout.java:842

        boxUnderlineDefault = new MaterialShapeDrawable();
        boxUnderlineFocused = new MaterialShapeDrawable();
        break;
      case BOX_BACKGROUND_OUTLINE:
        if (hintEnabled && !(boxBackground instanceof CutoutDrawable)) {
          boxBackground = CutoutDrawable.create(shapeAppearanceModel);
        } else {
          boxBackground = new MaterialShapeDrawable(shapeAppearanceModel);
        }
        boxUnderlineDefault = null;
        boxUnderlineFocused = null;
        break;
      case BOX_BACKGROUND_NONE:
        boxBackground = null;
        boxUnderlineDefault = null;
        boxUnderlineFocused = null;
        break;
      default:
        throw new IllegalArgumentException(
            boxBackgroundMode + " is illegal; only @BoxBackgroundMode constants are supported.");
    }
  }

  void updateEditTextBoxBackgroundIfNeeded() {
    if (editText == null
        || boxBackground == null
        // Only set boxBackground when edit text doesn't provide its own background.
        || (!boxBackgroundApplied && editText.getBackground() != null)
        || boxBackgroundMode == BOX_BACKGROUND_NONE) {
      return;
    }
    updateEditTextBoxBackground();
    boxBackgroundApplied = true;
  }

  private void updateEditTextBoxBackground() {
    Drawable editTextBoxBackground = getEditTextBoxBackground();

View on GitHub (pinned to ac7e18efee)

Solutions

1. Use the declared constants: TextInputLayout.BOX_BACKGROUND_NONE, BOX_BACKGROUND_FILLED, BOX_BACKGROUND_OUTLINE.
2. Validate/normalize any data-driven int to one of the three before calling setBoxBackgroundMode.
3. Check XML app:boxBackgroundMode values (none, filled, outline).

Example fix

// before
til.setBoxBackgroundMode(modeFromPrefs); // e.g. 5 -> throws

// after
int mode = (modeFromPrefs == BOX_BACKGROUND_FILLED || modeFromPrefs == BOX_BACKGROUND_OUTLINE)
    ? modeFromPrefs : BOX_BACKGROUND_NONE;
til.setBoxBackgroundMode(mode);

private boolean isValidBoxBackgroundMode(int mode) {
  return mode == TextInputLayout.BOX_BACKGROUND_NONE
      || mode == TextInputLayout.BOX_BACKGROUND_FILLED
      || mode == TextInputLayout.BOX_BACKGROUND_OUTLINE;
}
// usage: if (isValidBoxBackgroundMode(mode)) til.setBoxBackgroundMode(mode);

When it happens

Trigger: Calling setBoxBackgroundMode(arbitraryInt) with a value outside BOX_BACKGROUND_NONE/FILLED/OUTLINE; invalid app:boxBackgroundMode in XML.

Common situations: Passing an unvalidated persisted mode; using a constant that exists only in a different Material version; arithmetic or enum-mapping bugs that produce off-by-one values.

Related errors

• The current box background mode is not supported by the end
• endIconSize cannot be less than 0
• Invalid end icon mode:
• startIconSize cannot be less than 0
• There must be a keyline marked as focal.

AI-assisted analysis of material-components/material-components-android@ac7e18efee (2026-08-14). Data as JSON: /api/errors/9f4ce459df31101c. Report an issue: GitHub.