mermaid-js/mermaid · error · Error

Icon not found: ${iconName}

Error message

Icon not found: ${iconName}

What it means

Thrown by getRegisteredIconData after the pack (prefix) was successfully located/loaded, but getIconData(icons, data.name) from @iconify/utils returned null — i.e. the iconify pack doesn't contain an icon with that exact name. The pack is fine; the specific icon identifier within it is wrong or missing.

Source

Thrown at packages/mermaid/src/rendering-util/icons.ts:74

  }
  let icons = iconsStore.get(prefix);
  if (!icons) {
    const loader = loaderStore.get(prefix);
    if (!loader) {
      throw new Error(`Icon set not found: ${data.prefix}`);
    }
    try {
      const loaded = await loader();
      icons = { ...loaded, prefix };
      iconsStore.set(prefix, icons);
    } catch (e) {
      log.error(e);
      throw new Error(`Failed to load icon set: ${data.prefix}`);
    }
  }
  const iconData = getIconData(icons, data.name);
  if (!iconData) {
    throw new Error(`Icon not found: ${iconName}`);
  }
  return iconData;
};

export const isIconAvailable = async (iconName: string) => {
  try {
    await getRegisteredIconData(iconName);
    return true;
  } catch {
    return false;
  }
};

export const getIconSVG = async (
  iconName: string,
  customisations?: IconifyIconCustomisations & { fallbackPrefix?: string },
  extraAttributes?: Record<string, string>
) => {

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Look up the exact icon name in the registered pack's JSON or on icones.js.org for that specific pack version.
2. Watch for suffixes: some icons need `-fill`, `-line`, or a size like `-16`; match the variant that exists.
3. Register the correct pack that actually contains the icon, or switch the name to one the current pack provides.
4. Use isIconAvailable(name) before rendering to surface missing icons gracefully and avoid the throw.

Example fix

// before
getIconSVG('logos:reactt'); // typo
// after
getIconSVG('logos:react');

const ok = await mermaidAPI.isIconAvailable?.(name) ?? (await isIconAvailable(name));
if (!ok) throw new Error(`icon '${name}' not in its pack; check spelling/version`);

function iconExistsInPack(pack: any, iconName: string): boolean { return Boolean(pack?.icons?.[iconName] ?? pack?.aliases?.[iconName]); }

try { await getIconSVG(name); } catch (e) { if (/Icon not found/.test(String(e))) { return getIconSVG(`${prefix}:${altName}`); } throw e; }

When it happens

Trigger: Writing `logos:reactt` (typo) against a registered logos pack, referencing a legacy/renamed icon (e.g. the pack renamed `github` → `github-icon`), or asking for an icon from the wrong pack (e.g. `logos:home` when `home` lives in a different pack). Aliases and suffixes (:-fill, :-16) that don't exist in the pack also trigger this.

Common situations: Icon packs version changes that rename or remove glyphs, copying an icon name from icones.js.org but registering a different/older pack version, or assuming an icon exists without checking. In flowcharts/treeView, an icon: directive with a wrong name renders (getIconSVG falls back to unknownIcon) but isIconAvailable returns false because of this throw.

Related errors

• Invalid icon name: ${iconName}
• Icon name must contain a prefix: ${iconName}
• Invalid icon loader. Must have a "name" property with non-em
• Invalid icon loader. Must have either "icons" or "loader" pr
• Icon set not found: ${data.prefix}

AI-assisted analysis of mermaid-js/mermaid@d93e9c88c0 (2026-08-12). Data as JSON: /api/errors/09584d9f14df35c5. Report an issue: GitHub.