What causes "Invalid icon name: ${iconName}" in mermaid-js/mermaid?

Ensure icon names follow the iconify convention `prefix:name` (or `prefix-name`) with both segments non-empty, e.g. `logos:react`.

mermaid-js/mermaid · error

Invalid icon name: ${iconName}

Error message

Invalid icon name: ${iconName}

What it means

Thrown by getRegisteredIconData when @iconify/utils' stringToIcon(iconName, true, allowOptionalPrefix) returns null/undefined — meaning the raw icon name string cannot be parsed into a {prefix, name} pair at all. This is a malformed-name failure, distinct from a missing prefix (103). It happens during icon lookup from getIconSVG and isIconAvailable (where it is swallowed and returns false).

Source

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

        'Invalid icon loader. Must have a "name" property with non-empty string value.'
      );
    }
    log.debug('Registering icon pack:', iconLoader.name);
    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}`);

View on GitHub (pinned to d93e9c88c0)

Solutions

Ensure icon names follow the iconify convention `prefix:name` (or `prefix-name`) with both segments non-empty, e.g. `logos:react`.
Sanitize/validate the icon string before it reaches rendering: trim it and confirm it matches /^[a-z0-9-]+:[a-z0-9-]+$/i.
If using a fallbackPrefix via config, still supply a real icon name segment — the fallback only fills the prefix, not the name.
Use the isIconAvailable() helper to probe without throwing; it wraps getRegisteredIconData in try/catch and returns false.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const ICON_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$/i;
function isValidIconName(s: string): boolean { return typeof s === 'string' && ICON_NAME_RE.test(s.trim()); }
if (!isValidIconName(name)) throw new Error(`bad icon name: ${name}`);

Type guard

function isIconName(s: unknown): s is string {
  return typeof s === 'string' && s.includes(':') && s.split(':').every((p) => p.trim().length > 0);
}

Try / catch

try { await getIconSVG(name, opts); } catch (e) { if (/Invalid icon name/.test(String(e))) return fallbackSvg; throw e; }

Prevention

Always use the `prefix:name` form.
Sanitize user-supplied icon strings before rendering.
Prefer isIconAvailable() to probe names without throwing.

When it happens

Trigger: Passing an icon name that is not a valid iconify identifier: empty string, whitespace-only, names containing only a colon, names with invalid characters, or `:` with empty segments. e.g. getIconSVG(':') , getIconSVG('') , getIconSVG(':::'). stringToIcon's second arg is `true` (validate), so structurally broken strings return null.

Common situations: Dynamic icon name construction that yields empty segments (e.g. `${prefix}:${name}` where one var is undefined), reading icon names from user input without sanitization, or copy/paste with stray characters. In diagrams, an icon: directive whose value fails to parse surfaces here when the renderer resolves it.

Related errors

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