angular/components · error

Unable to find icon with the name "${name}"

Error message

Unable to find icon with the name "${name}"

What it means

When resolving an icon by name, the registry fetches all icon-set configs that may contain it and extracts the named SVG. If no set defines the name after all fetches complete, it throws this error because the requested icon simply isn't registered.

Source

Thrown at src/material/icon/icon-registry.ts:462

            // Swallow errors fetching individual URLs so the
            // combined Observable won't necessarily fail.
            const errorMessage = `Loading icon set URL: ${url} failed: ${err.message}`;
            this._errorHandler.handleError(new Error(errorMessage));
            return observableOf(null);
          }),
        );
      });

    // Fetch all the icon set URLs. When the requests complete, every IconSet should have a
    // cached SVG element (unless the request failed), and we can check again for the icon.
    return forkJoin(iconSetFetchRequests).pipe(
      map(() => {
        const foundIcon = this._extractIconWithNameFromAnySet(name, iconSetConfigs);

        // TODO: add an ngDevMode check
        if (!foundIcon) {
          throw getMatIconNameNotFoundError(name);
        }

        return foundIcon;
      }),
    );
  }

  /**
   * Searches the cached SVG elements for the given icon sets for a nested icon element whose "id"
   * tag matches the specified name. If found, copies the nested element to a new SVG element and
   * returns it. Returns null if no matching element is found.
   */
  private _extractIconWithNameFromAnySet(
    iconName: string,
    iconSetConfigs: SvgIconConfig[],
  ): SVGElement | null {
    // Iterate backwards, so icon sets added later have precedence.
    for (let i = iconSetConfigs.length - 1; i >= 0; i--) {

View on GitHub (pinned to 0411926e7d)

Solutions

1. Register the icon first: MatIconRegistry.addSvgIcon(name, url) or addSvgIconLiteral(name, html), ideally in an APP_INITIALIZER.
2. Verify exact name and namespace spelling/case (e.g. 'name' vs 'namespace:name').
3. Open the icon-set SVG and confirm the <symbol>/<g id="..."> with that name exists.
4. Check that the set's HTTP fetch isn't failing (network/404) — a failed fetch leaves the icon unresolvable.

Example fix

// before
// template: <mat-icon svgIcon="custom:home"></mat-icon>  (never registered)
// after
// in app initializer:
registry.addSvgIconLiteralInNamespace(
  'custom', 'home',
  sanitizer.bypassSecurityTrustHtml('<svg>...</svg>'),
);

// before rendering an svgIcon, verify registration
async function assertIconRegistered(registry: MatIconRegistry, name: string) {
  try { await registry.getNamedSvgIcon(name).toPromise(); }
  catch { throw new Error(`Icon "${name}" must be registered in APP_INITIALIZER`); }
}

try {
  await firstValueFrom(registry.getNamedSvgIcon(name));
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unable to find icon')) {
    console.warn(`Icon "${name}" missing — falling back to default icon.`);
    this.fallbackIcon = 'default';
  } else { throw e; }
}

When it happens

Trigger: Using <mat-icon svgIcon="namespace:iconName"> (or getNamedSvgIcon) where the name was never registered via addSvgIcon/addSvgIconLiteral/addSvgIconSet, a namespace typo, or the icon missing from a remote SVG set file (or the fetch failing silently upstream).

Common situations: Icon name or namespace case-mismatch with registration; remote sprite updated and the icon renamed/removed; registration code (AppInit/bootstrapping) not run before first render; using svgIcon when the icon was registered without a namespace prefix (or vice versa).

Related errors

• MatTimepicker can only be registered with one input at a tim
• The literal provided to MatIconRegistry was not trusted as s
• The URL provided to MatIconRegistry was not trusted as a res
• <svg> tag not found
• Cannot fetch icon from URL "${safeUrl}".

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