Docusaurus Build Fails with EEXIST Error for index.html

Question

I'm encountering an error when attempting to build my Docusaurus project using yarn build. The build process fails with an EEXIST file already exists error for the index.html file. This issue doesn't occur during development mode (yarn start), but consistently appears when building for production. I'm using Docusaurus version 3.5.2 and Node version 22.5.1.

Here are the relevant parts of my package.json dependencies:

Docusaurus packages like @docusaurus/core, @docusaurus/plugin-client-redirects, etc., at version 3.5.2 AWS Amplify related packages TypeScript at version 5.0.3 Various plugins like docusaurus-plugin-sass, docusaurus-plugin-typedoc

The error log is as follows:

[ERROR] Redirect file creation error for "build/docs/index.html".
[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (node_modules/@docusaurus/core/lib/commands/build.js:54:19)
    at async node_modules/@docusaurus/core/lib/commands/build.js:65:9
    at async mapAsyncSequential (node_modules/@docusaurus/utils/lib/jsUtils.js:21:24)
    at async Command.build (node_modules/@docusaurus/core/lib/commands/build.js:63:5) {
  cause: [Error: EEXIST: file already exists, open 'build/docs/index.html'] {
    errno: -17,
    code: 'EEXIST',
    syscall: 'open',
    path: 'build/docs/index.html'
  }
}

Steps I've tried:

• Ensuring no process is locking the index.html file.
• Manually deleting the build directory before running yarn build. Any suggestions on how to resolve this issue would be greatly appreciated. Thank you!

I attempted to resolve the issue by ensuring that no processes were locking the index.html file and manually deleting the build directory before attempting to rebuild the project. I also checked for any misconfigurations in my docusaurus.config.js and related setup files that might lead to file path conflicts.

Answer 1

I managed to resolve the build error by adjusting the redirection settings in the Docusaurus configuration file. The issue stemmed from overlapping redirection rules that were causing a conflict during the build process.

Issue Detail:

The EEXIST error indicated that the build process was attempting to create a file that already existed. This was happening because there were two redirections in the @docusaurus/plugin-client-redirects configuration that essentially pointed to the same target from very similar sources:

[
  '@docusaurus/plugin-client-redirects',
  {
    redirects: [
      {
        to: '/docs/intro',
        from: '/docs',
      },
      {
        to: '/docs/intro',
        from: '/docs/',
      },
    ],
  },
]

The above setup tried to redirect both /docs and /docs/ to /docs/intro, which likely caused the file handling conflict seen as an EEXIST error during the build process.

Solution Implementation:

To fix this, I removed the redundant redirection from the configuration:

[
  '@docusaurus/plugin-client-redirects',
  {
    redirects: [
      {
        to: '/docs/intro',
        from: '/docs',
      },
    ],
  },
]

By keeping only one redirection rule, the conflict was resolved, allowing the build to complete successfully without errors.