facebook / facebook/docusaurus

Zero-width space in mdx file path => build fails due to hash mismatch

Open
#12,005 7 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).

### Prerequisites

- [x] I'm using the latest version of Docusaurus.
- [x] I have tried the `npm run clear` or `yarn clear` command.
- [x] 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.
(because of the network problem, I can't work with CodeSandbox and StackBlitz, but it can reproduce in the clean new project)
- [x] I have read the console error message carefully (if applicable).

### Description

1. In a fresh Docusaurus project on Windows using npm, creating `docs/contribute/index.mdx` works fine.
2. However, moving that same file into `docs/contribute/vulnerability-report/index.mdx` causes the build to fail.
Image
4. Renaming the folder `vulnerability-report` to `foo-bar` resolves the issue.
Image
6. Moving the file back to `docs/contribute/index.mdx` also resolves it. The problem occurs with both `.mdx` and `.md` extensions.
7. Moving the file back to `docs/contribute/vulnerability-report/index.mdx` again, the build fail again.

### Reproducible demo

https://github.com/coder-xiaomo/docusaurus-bug-minimal-repro/commits/main/

Image

### Steps to reproduce

1. Create a new Docusaurus project using npm on Windows:
```bash
npx create-docusaurus@latest my-website classic --typescript
cd my-website
npm install
```

2. Create a file `docs/contribute/index.mdx` with any content (e.g., `# Test`).

3. Run `npm start` – the site builds successfully and the doc displays at `/docs/contribute`.

4. Stop the server. Move the file into a new subdirectory `vulnerability-report`:
```bash
mkdir docs\contribute\vulnerability-report
move docs\contribute\index.mdx docs\contribute\vulnerability-report\index.mdx
```
Then run `npm start` – **build fails** (error details below).

5. Stop the server. Clean the cache and dependencies:
```bash
rmdir /s /q .docusaurus
rmdir /s /q node_modules
npm install
```
After reinstallation, run `npm start` again – **the error still occurs**.

6. Stop the server. Rename the `vulnerability-report` folder to `foo-bar`:
```bash
move docs\contribute\vulnerability-report docs\contribute\foo-bar
```
Run `npm start` – **the build now works correctly**.

7. Stop the server. Move the file back to `docs/contribute/index.mdx`:
```bash
move docs\contribute\foo-bar\index.mdx docs\contribute\index.mdx
```
Run `npm start` – **the build works correctly again**.

8. (Optional) Repeat the same steps using a `.md` file instead of `.mdx` – **the problem is reproducible exactly the same way**.

### Expected behavior

The build should succeed, and the doc should be accessible at `/docs/contribute/vulnerability-report` without any hash mismatch. Deleting `.docusaurus` and `node_modules` should not be necessary for a correct build.

### Actual behavior

When the file is located at `docs/contribute/vulnerability-report/index.mdx`, the build fails with a module resolution error:

```
× Cannot find module '@site/.docusaurus/docusaurus-plugin-content-docs/default/site-docs-contribute-vulnerability-report-index-mdx-e58.json' for matched aliased key '@site'
```

Image

Meanwhile, inside `.docusaurus/docusaurus-plugin-content-docs/default/`, the actual generated file is:

```
site-docs-contribute-vulnerability-report-index-mdx-b66.json
```

**Notice the hash mismatch: looking for `-e58` but the file exists with `-b66`.**

Image

### Your environment

- Public source code: https://github.com/coder-xiaomo/docusaurus-bug-minimal-repro/commits/main/
- Public site URL:
- Docusaurus version used: latest (3.10.1)
- Environment name and version: Microsoft Edge 147.0.3912.98; Node.js v24.14.1
- Operating system and version: Windows 11

### Self-service

- [x] I'd be willing to fix this bug myself. (but I am not sure where the root cause is. If the root cause was found, maybe I can create an pull request to fix it)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.