Mermaid-related build-errors in v3.9.1 (regression)

[Zamiell]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

After upgrading my Docusaurus project, I get a build error:

james@1qaz MSYS /d/Repositories/hanabi.github.io (main)
$ u

> update
> complete-cli update

Upgrading D:\Repositories\hanabi.github.io\package.json
[====================] 20/20 100%

 @docusaurus/core            3.8.1  →  3.9.1
 @docusaurus/faster          3.8.1  →  3.9.1
 @docusaurus/preset-classic  3.8.1  →  3.9.1
 @docusaurus/theme-mermaid   3.8.1  →  3.9.1
 @docusaurus/tsconfig        3.8.1  →  3.9.1

Run npm install to install new versions.

added 33 packages, removed 13 packages, changed 124 packages, and audited 1895 packages in 23s

538 packages are looking for funding
  run `npm fund` for details

3 vulnerabilities (1 low, 2 moderate)

To address all issues, run:
  npm audit fix

Run `npm audit` for details.
Successfully installed new dependencies.

james@1qaz MSYS /d/Repositories/hanabi.github.io (main)
$ b

> build
> tsx --tsconfig ./scripts/tsconfig.json ./scripts/build.mts

[SUCCESS] Removed the build output folder at "build".
[SUCCESS] Removed the generated folder at ".docusaurus".
[SUCCESS] Removed the bundler persistent cache folder at "node_modules\.cache".
[WARNING] The `siteConfig.onBrokenMarkdownLinks` config option is deprecated and will be removed in Docusaurus v4.
Please migrate and move this option to `siteConfig.markdown.hooks.onBrokenMarkdownLinks` instead.
[INFO] [en] Creating an optimized production build...
[WARNING] The `siteConfig.onBrokenMarkdownLinks` config option is deprecated and will be removed in Docusaurus v4.
Please migrate and move this option to `siteConfig.markdown.hooks.onBrokenMarkdownLinks` instead.
● Client ██████████████████████████████████████████████████ (100%) emitting after emit
● Server ██████████████████████████████████████████████████ (93%) sealing after asset optimization
[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (D:\Repositories\hanabi.github.io\node_modules\@docusaurus\core\lib\commands\build\build.js:83:15)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async D:\Repositories\hanabi.github.io\node_modules\@docusaurus\core\lib\commands\build\build.js:35:9
    at async mapAsyncSequential (D:\Repositories\hanabi.github.io\node_modules\@docusaurus\utils\lib\jsUtils.js:21:24)
    at async Command.build (D:\Repositories\hanabi.github.io\node_modules\@docusaurus\core\lib\commands\build\build.js:34:5)
    at async Promise.all (index 0)
    at async runCLI (D:\Repositories\hanabi.github.io\node_modules\@docusaurus\core\lib\commands\cli.js:56:5)
    at async file:///D:/Repositories/hanabi.github.io/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
  [cause]: Error: Failed to compile due to Webpack errors.
  × Module not found: Can't resolve '@mermaid-js/layout-elk' in 'D:\Repositories\hanabi.github.io\node_modules\@docusaurus\theme-mermaid\lib\client'
       ╭─[139:24]
   137 │                     return [
   138 │                         4,
   139 │                         import('@mermaid-js/layout-elk')
       ·                         ────────────────────────────────
   140 │                     ];
   141 │                 case 1:
       ╰────
      at D:\Repositories\hanabi.github.io\node_modules\@docusaurus\bundler\lib\compiler.js:49:24
      at D:\Repositories\hanabi.github.io\node_modules\@rspack\core\dist\index.js:11875:68
      at processQueueWorker (D:\Repositories\hanabi.github.io\node_modules\@rspack\core\dist\index.js:11854:41)
      at process.processTicksAndRejections (node:internal/process/task_queues:85:11)
}
[INFO] Docusaurus version: 3.9.1
Node version: v22.19.0
The following command exited with a code of 1: docusaurus build

This looks to be an internal Docusaurus error. When I revert the dependencies back to 3.8.1, my project builds successfully again, so it seems to be a regression.

Your environment

• Public source code: https://github.com/hanabi/hanabi.github.io/
• Public site URL:https://hanabi.github.io/
• Docusaurus version used: 3.9.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node v22.19.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 10

Self-service

• I'd be willing to fix this bug myself.

[cnaples79]

This issue is already fixed on the main branch in PR #11437 (commit b4cc50a).

Root Cause:
v3.9.1 has a bug where the Rspack bundler tries to resolve @mermaid-js/layout-elk even when it's not installed (it's an optional peer dependency). This happens specifically with Rspack + SWC loader on the server-side config.

The Fix:
The fix adds a webpack resolve alias that sets @mermaid-js/layout-elk to false when the package is not available, preventing the resolution error:

resolve: {
  alias: {
    ...(elkLayoutEnabled
      ? {}
      : {
          '@mermaid-js/layout-elk': false,
        }),
  },
}

Workarounds until the next release:

1. Install the optional dependency: npm install @mermaid-js/layout-elk
2. Downgrade to v3.8.1 (as you've already discovered)
3. Use the canary release: npm install @docusaurus/core@canary @docusaurus/theme-mermaid@canary etc.

Timeline:
The fix was committed on Sept 26, 2025, after v3.9.1 was released. It will be included in the next release (likely v3.9.2 or v3.10.0).

This appears to be a duplicate of #11430. The maintainers may want to consider closing this as duplicate once the information is noted.

[Zamiell]

Shouldn't issue #11430 stay open until the fix is actually published?

[cnaples79]

@Zamiell probably yes. I was about to open a PR for this and wanted to contribute my findings! I'm not a maintainer of this repo.

[slorber]

Shouldn't issue #11430 stay open until the fix is actually published?

The fix is published and available in Canary release channels.

We usually close issues when they get fixed on main. This practice is also encouraged by GitHub, which automatically closes the linked issue on PR merge.