VitePress "dead links found" build failed in CI

By Kaveh Alemi·Latchkey

VitePress checks every internal Markdown link against the generated pages. When a link points to a path that no page produces, the build fails and lists the dead links and their source files.

What this error means

vitepress build ends with "Build failed due to dead links found in file ..." listing each broken internal link and the file that contains it.

( ! ) Found dead link ./guide/setup in file index.md
The link points to a page that does not exist.

Build failed due to dead links.

Common causes

A link to a moved or missing page

A Markdown link references a path with no corresponding file, often after renaming or deleting a page.

A wrong relative path or extension

Linking with the wrong relative depth, or including .html where VitePress expects the source path, makes the target unresolvable.

How to fix it

Fix the link to a real page

1. Read the listed dead link and its source file.
2. Point it at an existing page using the correct relative path.
3. Re-run the build to confirm no dead links remain.

[Setup](./guide/getting-started)

Allow specific external or pattern links

If a link is intentionally external or generated, configure ignoreDeadLinks narrowly rather than disabling the check entirely.

export default {
  ignoreDeadLinks: [/^https?:\/\//, './generated/'],
};

How to prevent it

• Use correct relative paths without .html extensions.
• Update internal links when pages move or are renamed.
• Scope ignoreDeadLinks narrowly instead of turning the check off.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation