MkDocs "contains a link ... not found among documentation files" (strict) in CI

By Kaveh Alemi·Latchkey

A Markdown page links to another doc that MkDocs cannot resolve to a file. Normally this is a warning; with --strict it becomes a BuildError and fails CI.

What this error means

mkdocs build (with --strict) reports "Doc file 'X.md' contains a link 'Y.md' which is not found in the documentation files" and aborts.

WARNING  -  Doc file 'guide/index.md' contains a link 'setup.md', but the target
'guide/setup.md' is not found among documentation files.
Aborted with a BuildError!

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

The linked page was moved or renamed

The relative link still points to the old path after the target file was renamed or relocated under docs/.

A wrong relative path

The link is relative to the current file; an incorrect prefix or missing directory makes MkDocs unable to resolve it.

How to fix it

Correct the relative link

1. Read the source file and target the warning names.
2. Fix the link to the real relative path of the target Markdown file.
3. Rebuild with --strict to confirm it resolves.

[Setup guide](../setup.md)

Keep links as Markdown file paths

Link to the source .md files (not the built URLs) so MkDocs can validate them at build time.

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

• Link to source .md files using correct relative paths.
• Update links whenever you move or rename pages.
• Run mkdocs build --strict so broken links fail CI.

Frequently asked questions

Related guides

References

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