{"record":{"id":"514f05909dd8d42e","repo":"mermaid-js/mermaid","slug":"icon-name-must-contain-a-prefix-iconname","errorCode":null,"errorMessage":"Icon name must contain a prefix: ${iconName}","messagePattern":"Icon name must contain a prefix: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/mermaid/src/rendering-util/icons.ts","lineNumber":55,"sourceCode":"    if ('loader' in iconLoader) {\n      loaderStore.set(iconLoader.name, iconLoader.loader);\n    } else if ('icons' in iconLoader) {\n      iconsStore.set(iconLoader.name, iconLoader.icons);\n    } else {\n      log.error('Invalid icon loader:', iconLoader);\n      throw new Error('Invalid icon loader. Must have either \"icons\" or \"loader\" property.');\n    }\n  }\n};\n\nconst getRegisteredIconData = async (iconName: string, fallbackPrefix?: string) => {\n  const data = stringToIcon(iconName, true, fallbackPrefix !== undefined);\n  if (!data) {\n    throw new Error(`Invalid icon name: ${iconName}`);\n  }\n  const prefix = data.prefix || fallbackPrefix;\n  if (!prefix) {\n    throw new Error(`Icon name must contain a prefix: ${iconName}`);\n  }\n  let icons = iconsStore.get(prefix);\n  if (!icons) {\n    const loader = loaderStore.get(prefix);\n    if (!loader) {\n      throw new Error(`Icon set not found: ${data.prefix}`);\n    }\n    try {\n      const loaded = await loader();\n      icons = { ...loaded, prefix };\n      iconsStore.set(prefix, icons);\n    } catch (e) {\n      log.error(e);\n      throw new Error(`Failed to load icon set: ${data.prefix}`);\n    }\n  }\n  const iconData = getIconData(icons, data.name);\n  if (!iconData) {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/mermaid-js/mermaid/blob/d93e9c88c01a599c062ee6a3f1462e3558ac6b90/packages/mermaid/src/rendering-util/icons.ts#L37-L73","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reference icons with their pack prefix: `logos:react` rather than `react`.","Set a fallbackPrefix in the icon customisations/config so bare names resolve to a default registered pack.","Register the pack under the prefix you intend to use so the prefix segment matches a known registry key.","Probe with isIconAvailable() during development to catch prefix-less names before render."],"exampleFix":"// before\ngetIconSVG('react');\n// after\ngetIconSVG('logos:react'); // or\ngetIconSVG('react', { fallbackPrefix: 'logos' });","handlingStrategy":"validation","validationCode":"function ensurePrefix(name: string, fallbackPrefix?: string): string {\n  if (name.includes(':')) return name;\n  if (fallbackPrefix) return `${fallbackPrefix}:${name}`;\n  throw new Error(`icon name '${name}' has no prefix and no fallbackPrefix given`);\n}\ngetIconSVG(ensurePrefix(rawName, 'logos'), { fallbackPrefix: 'logos' });","typeGuard":"function hasIconPrefix(s: string, allowMissingPrefix: boolean): boolean {\n  return allowMissingPrefix ? true : /^[^:]+:.+$/.test(s);\n}","tryCatchPattern":"try { await getIconSVG(name); } catch (e) { if (/must contain a prefix/.test(String(e))) { return getIconSVG(`${defaultPrefix}:${name}`); } throw e; }","preventionTips":["Always write icons with their pack prefix.","Configure a fallbackPrefix in mermaidConfig if you support bare names.","Validate prefix presence in user-authored diagram text."],"tags":["icons","validation","iconify","configuration"],"backgroundTag":null,"analyzedSha":"d93e9c88c01a599c062ee6a3f1462e3558ac6b90","analyzedAt":"2026-08-12T06:23:11.304Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}