mermaid-js/mermaid · error · Error

Icon set not found: ${data.prefix}

Error message

Icon set not found: ${data.prefix}

What it means

Thrown by getRegisteredIconData when the resolved prefix is found in neither iconsStore (static packs) nor loaderStore (async packs). The prefix exists in the icon name but no registerIconPacks call ever registered a pack under that prefix key. Note the message uses data.prefix (the parsed prefix), not the fallback — if the name had no prefix, the fallback is what was tried.

Source

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

      throw new Error('Invalid icon loader. Must have either "icons" or "loader" property.');
    }
  }
};

const getRegisteredIconData = async (iconName: string, fallbackPrefix?: string) => {
  const data = stringToIcon(iconName, true, fallbackPrefix !== undefined);
  if (!data) {
    throw new Error(`Invalid icon name: ${iconName}`);
  }
  const prefix = data.prefix || fallbackPrefix;
  if (!prefix) {
    throw new Error(`Icon name must contain a prefix: ${iconName}`);
  }
  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) => {

View on GitHub (pinned to d93e9c88c0)

Solutions

  1. Call mermaid.registerIconPacks([{ name: '<prefix>', loader: () => import('@iconify-json/<prefix>') }]) before the diagram renders.
  2. Make sure the `name` you register equals the prefix segment used in icon names (e.g. name: 'logos' ⇔ logos:react).
  3. If using a CDN/fetch loader, verify the network request resolves and the JSON has the expected shape.
  4. Confirm registerIconPacks runs in the same module/bundle instance that renders — split bundles can leave the registry empty.

Example fix

// before
mermaid.render(...) // referencing logos:react, nothing registered
// after
mermaid.registerIconPacks([
  { name: 'logos', loader: () => import('@iconify-json/logos').then((m) => m.icons) },
]);
mermaid.render(...); // logos:react now resolves
Defensive patterns

Strategy: validation

Validate before calling

const registered = new Set(['logos', 'fa']); // mirrors registerIconPacks calls
function isRegisteredPrefix(p: string): boolean { return registered.has(p); }
if (!isRegisteredPrefix(prefix)) throw new Error(`prefix '${prefix}' not registered; call registerIconPacks`);

Type guard

function isKnownPrefix(p: string, known: string[]): p is string { return known.includes(p); }

Try / catch

try { await getIconSVG(name); } catch (e) { if (/Icon set not found/.test(String(e))) { await ensurePackRegistered(prefix); return getIconSVG(name); } throw e; }

Prevention

When it happens

Trigger: Referencing `fa:github` without ever calling registerIconPacks([{ name: 'fa', loader }]), or using a prefix that doesn't match the `name` you registered (registered 'fontawesome' but wrote 'fa:...'). Also when includeLargeFeatures/build stripped the pack import, or the registerIconPacks call hasn't run yet at lookup time.

Common situations: Forgetting to call registerIconPacks at app boot, calling it after the diagram renders, a typo between the registered name and the prefix used in the diagram, or using a CDN bundle that doesn't include the pack. In treeView/architecture diagrams the renderer calls registerIconPacks internally for some packs but not arbitrary ones.

Related errors

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