mermaid-js/mermaid · error

Icon name must contain a prefix: ${iconName}

Error message

Icon name must contain a prefix: ${iconName}

What it means

Thrown by getRegisteredIconData when stringToIcon parsed the name but produced no prefix AND no fallbackPrefix was supplied. iconify icon names are namespaced by prefix (the pack), so without one the registry cannot be looked up. This is the prefix-missing twin of 102 (which fires on totally unparseable strings).

Source

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

    if ('loader' in iconLoader) {
      loaderStore.set(iconLoader.name, iconLoader.loader);
    } else if ('icons' in iconLoader) {
      iconsStore.set(iconLoader.name, iconLoader.icons);
    } else {
      log.error('Invalid icon loader:', iconLoader);
      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) {

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Reference icons with their pack prefix: `logos:react` rather than `react`.
2. Set a fallbackPrefix in the icon customisations/config so bare names resolve to a default registered pack.
3. Register the pack under the prefix you intend to use so the prefix segment matches a known registry key.
4. Probe with isIconAvailable() during development to catch prefix-less names before render.

Example fix

// before
getIconSVG('react');
// after
getIconSVG('logos:react'); // or
getIconSVG('react', { fallbackPrefix: 'logos' });

function ensurePrefix(name: string, fallbackPrefix?: string): string {
  if (name.includes(':')) return name;
  if (fallbackPrefix) return `${fallbackPrefix}:${name}`;
  throw new Error(`icon name '${name}' has no prefix and no fallbackPrefix given`);
}
getIconSVG(ensurePrefix(rawName, 'logos'), { fallbackPrefix: 'logos' });

function hasIconPrefix(s: string, allowMissingPrefix: boolean): boolean {
  return allowMissingPrefix ? true : /^[^:]+:.+$/.test(s);
}

try { await getIconSVG(name); } catch (e) { if (/must contain a prefix/.test(String(e))) { return getIconSVG(`${defaultPrefix}:${name}`); } throw e; }

When it happens

Trigger: Calling getIconSVG('react') (bare name, no prefix) while not passing a fallbackPrefix, or a diagram referencing an unprefixed icon when the global fallbackPrefix config is unset. With stringToIcon(iconName, true, fallbackPrefix !== undefined), when fallbackPrefix is undefined the prefix becomes mandatory.

Common situations: User writes `icon: react` expecting a default pack but no fallback is configured; or a treeView/architecture diagram references an icon by short name without registering a fallbackPrefix in mermaidConfig. Also after migrating icon syntax where the prefix was previously implied.

Related errors

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

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