mermaid-js/mermaid · error · Error

Failed to load icon set: ${data.prefix}

Error message

Failed to load icon set: ${data.prefix}

What it means

Thrown by getRegisteredIconData when an async loader for the prefix was found but invoking it rejected/threw. The original error is logged via log.error(e) first, then this generic message is thrown wrapping the context (which prefix failed). The loaded JSON is cached into iconsStore only on success, so a failure leaves the pack unregistered and the next lookup retries the loader.

Source

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

    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) => {
  try {
    await getRegisteredIconData(iconName);
    return true;
  } catch {
    return false;
  }
};

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Check the console: log.error(e) prints the underlying cause (HTTP status, import error) immediately before this message.
2. Verify the loader actually resolves to an IconifyJSON object — for imports use .then((m) => m.icons), for fetch add .then((r) => r.json()).
3. Confirm network access/CORS for CDN loaders, and that the package is installed for bundler-based imports.
4. Add error handling inside the loader or fall back to a static `icons` pack if the async source is unreliable.

Example fix

// before — import path wrong / no .icons
{ name: 'logos', loader: () => import('@iconify-json/logos') }
// after
{
  name: 'logos',
  loader: () => import('@iconify-json/logos').then((m) => m.icons),
}

async function safeLoad(prefix: string, loader: () => Promise<any>) {
  try { return await loader(); }
  catch (e) { console.error(`icon loader for ${prefix} failed`, e); throw e; }
}

function isIconifyJSON(x: any): x is { icons: Record<string, unknown>; prefix: string } {
  return x && typeof x === 'object' && 'icons' in x;
}

try { await getIconSVG(name); } catch (e) { if (/Failed to load icon set/.test(String(e))) { /* maybe retry once, or register a static pack */ } throw e; }

When it happens

Trigger: A loader whose fetch/import throws: network failure on fetch('https://unpkg.com/.../icons.json'), a broken dynamic import path, the imported module not exposing `.icons`, or the resolver returning non-JSON. e.g. loader: () => import('@iconify-json/missing-pack').

Common situations: Offline/CORS-blocked CDN fetches, a typoed npm package name in the loader, an ESM/CJS interop where `module.icons` is undefined (then `{...undefined, prefix}` produces a bad pack that fails later), or a transient network error during lazy load.

Related errors

• Failed to load ${failed.length} external diagrams
• Invalid icon name: ${iconName}
• Icon name must contain a prefix: ${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/c71a22ee71aed35f. Report an issue: GitHub.