mermaid-js/mermaid · error

Failed to load external diagrams

Error message

Failed to load ${failed.length} external diagrams

What it means

Thrown by loadDiagram when one or more external diagram loaders reject during Promise.allSettled. Each loader is an async module import; if any fails (network error, bad chunk path, runtime error in module), the failed count is aggregated and the whole batch is reported as failed after logging each rejection.

Solutions

1. Check the browser console/network tab for the failing chunk import (404, CORS, etc.).
2. Correct the asset base URL / public path so chunks resolve.
3. Ensure the external diagram package version matches the host mermaid version.
4. Catch the aggregate error and fall back to built-in diagrams, or retry the load.

Example fix

// before
await loadDiagram(loaders);

// after
try {
  await loadDiagram(loaders);
} catch (e) {
  console.error('External diagrams failed, continuing with built-ins', e);
  // degrade gracefully without the external diagrams
}

// Verify each chunk URL resolves before batch loading
async function probe(url: string) {
  const res = await fetch(url, { method: 'HEAD' });
  if (!res.ok) throw new Error(`Missing chunk: ${url}`);
}
await Promise.all(chunks.map(probe));
await loadDiagram(loaders);

try {
  await loadDiagram(loaders);
} catch (e) {
  // log and continue with built-in diagrams only
  console.error('External diagrams unavailable', e);
}

When it happens

Trigger: A dynamic import() for an external diagram chunk fails: 404 on the JS file, network offline, CORS block, syntax error in the chunk, or a peer dependency missing at runtime.

Common situations: Deploying a mermaid build where chunk paths are wrong (base URL misconfigured), CDN outage, ad-blocker stripping the chunk, or a version mismatch between the host and the external diagram package.

Related errors

• Diagram not found.
• Failed to load icon set
• Block start is greater than block end .
• Commit positions not found for commits
• Diagram not found.

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

Appendix: source

Thrown at packages/mermaid/src/diagram-api/loadDiagram.ts:35

          // Register diagram if it is not already registered
          const { diagram, id } = await loader();
          registerDiagram(id, diagram, detector);
        } catch (err) {
          // Remove failed diagram from detectors
          log.error(`Failed to load external diagram with key ${key}. Removing from detectors.`);
          delete detectors[key];
          throw err;
        }
      }
    })
  );
  const failed = results.filter((result) => result.status === 'rejected');
  if (failed.length > 0) {
    log.error(`Failed to load ${failed.length} external diagrams`);
    for (const res of failed) {
      log.error(res);
    }
    throw new Error(`Failed to load ${failed.length} external diagrams`);
  }
};

View on GitHub (pinned to d93e9c88c0)