Broken link while file exists

[aiboost]

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

When referring to some static file in the component like:

<Link href="/static/download/file.zip">Download</Link>

everything works fine on debug version.
But when I try to do "npm run build" I get the message:

Exhaustive list of all broken links found:
  - Broken link on source page path = /docs/my-page:
     -> linking to /download/file.zip

I definitely see that this file exists both as "/static/download/file.zip" and as "/build/download/file.zip".

Switching from to or using "path://" instead fixes building the website, but in this case I lose broken links checking.

Reproducible demo

No response

Steps to reproduce

1. Refer with Link to some existing file in static/: <Link href="/static/download/file.zip">Download</Link>
2. Run npm run build

Expected behavior

Build successes. It should fail only if file doesn't exist.

Actual behavior

Build failed:

Exhaustive list of all broken links found:
  - Broken link on source page path = /docs/my-page:
     -> linking to /download/file.zip

Your environment

• Docusaurus version used: 3.9.1
• Environment name and version: Node 18
• Operating system and version: Ubuntu 20.04 LTS

[TusharSharma811]

You’re running into how Docusaurus treats links at build time:

The broken-link checker validates links to internal routes (pages) only. Static assets under static/ are not routes.
Using a leading “/” makes the link look like an internal route “/download/file.zip”, which doesn’t exist as a route, so the build fails even though the file is present in the output.

What to do instead

Link to the static asset with baseUrl awareness (recommended)
Don’t include “/static” in the URL (that folder is mounted at site root).
Use useBaseUrl so it also works when your site has a non-root baseUrl.

Example (JSX/MDX): import Link from '@docusaurus/Link'; import useBaseUrl from '@docusaurus/useBaseUrl';

Download Or with a plain anchor: Download

Import the asset so the build fails if the file is missing (strongest guarantee)
This makes Webpack/Vite resolve the file and will error during build if it can’t be found.
Example: import zipUrl from '@site/static/download/file.zip';

Download

In Markdown/MDX, you can also use pathname://
This avoids route validation and still respects baseUrl.
Download

Notes

Remove “/static” from your URLs. The correct public path is /download/file.zip (or with baseUrl prefixed).
Prefer useBaseUrl over hardcoded “/” so links work when deploying under a subpath.
The Docusaurus broken-link checker does not validate the existence of static files; it validates routes. If you want a build-time guarantee that the file exists, option (2) is best. If you just want a working link with baseUrl handled, option (1) or (3) is fine.