What causes "Invalid icon name: "${iconName}"" in angular/components?

Ensure the bound string matches 'name' or 'namespace:name' with at most one colon.

Invalid icon name: "${iconName}"

Error message

Invalid icon name: "${iconName}"

What it means

MatIcon._splitIconName splits the svgIcon input on ':' into [namespace, name]; names with more than one colon cannot be parsed, so it throws 'Invalid icon name'. Valid forms are 'name' (default namespace) or 'namespace:name'.

Source

Thrown at src/material/icon/icon.ts:285

   * Throws an error if the name contains two or more ':' separators.
   * Examples:
   *   `'social:cake' -> ['social', 'cake']
   *   'penguin' -> ['', 'penguin']
   *   null -> ['', '']
   *   'a:b:c' -> (throws Error)`
   */
  private _splitIconName(iconName: string): [string, string] {
    if (!iconName) {
      return ['', ''];
    }
    const parts = iconName.split(':');
    switch (parts.length) {
      case 1:
        return ['', parts[0]]; // Use default namespace.
      case 2:
        return <[string, string]>parts;
      default:
        throw Error(`Invalid icon name: "${iconName}"`); // TODO: add an ngDevMode check
    }
  }

  ngOnInit() {
    // Update font classes because ngOnChanges won't be called if none of the inputs are present,
    // e.g. <mat-icon>arrow</mat-icon> In this case we need to add a CSS class for the default font.
    this._updateFontIconClasses();
  }

  ngAfterViewChecked() {
    const cachedElements = this._elementsWithExternalReferences;

    if (cachedElements && cachedElements.size) {
      const newPath = this._location.getPathname();

      // We need to check whether the URL has changed on each change detection since
      // the browser doesn't have an API that will let us react on link clicks and
      // we can't depend on the Angular router. The references need to be updated,

View on GitHub (pinned to 0411926e7d)

Solutions

Ensure the bound string matches 'name' or 'namespace:name' with at most one colon.
Pre-process icon keys: strip or replace extra colons before binding, e.g. name.split(':').slice(0,2).join(':').
Register/lookup with a namespace argument instead of encoding it in the name when data is unreliable.

Example fix

// before
<mat-icon [svgIcon]="'fa:home:regular'"></mat-icon>
// after
<mat-icon [svgIcon]="'fa:home'"></mat-icon>

Defensive patterns

Strategy: validation

Validate before calling

const ICON_NAME_RE = /^(?!.*:.*:)[\w-]+(?::[\w-]+)?$/;
if (!ICON_NAME_RE.test(iconName)) {
  throw new Error(`Icon name must be "name" or "namespace:name": got "${iconName}"`);
}
icon.svgIcon = iconName;

Type guard

function isValidIconName(v: unknown): v is string {
  return typeof v === 'string' &&
    /^[\w-]+(?::[\w-]+)?$/.test(v) &&
    (v.match(/:/g) ?? []).length <= 1;
}

Try / catch

try {
  icon.svgIcon = rawKey;
} catch (e) {
  if ((e as Error).message.startsWith('Invalid icon name')) {
    icon.svgIcon = rawKey.split(':').slice(0, 2).join(':');
  } else { throw e; }
}

Prevention

Normalize backend/CMS icon keys before binding them to [svgIcon]
Keep icon identifiers colon-free except for the single namespace separator
Type icon name unions as 'name' | `${string}:${string}` to catch bad keys at compile time

When it happens

Trigger: Setting <mat-icon [svgIcon]="expr"> where expr contains two or more colons, e.g. 'ns:a:b', or binding an icon key from config data that includes colons (full URLs, FontAwesome 'fa:xxx:y').

Common situations: Feeding icon identifiers from CMS/backend data that use ':' as separators; concatenating strings and accidentally double-joining; passing an entire URL as the icon name.

Related errors

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