mkdocs build "Aborted with 1 errors in strict mode"

TL;DR

Do not drop strict mode; fix the underlying warning. Run the build without strict to see the full warning list, fix each one (missing files, bad links, plugin misconfig), then re-enable strict and confirm a clean build.

The exact error

Aborted with 1 errors in strict mode

Steps

1. Reproduce without strict Run mkdocs build without --strict and collect the full warning output. Strict mode hides the detail behind the abort message. Success check: You have the complete list of warnings that strict mode escalated.

2. Fix each warning at the source For missing files, add or remove the nav entry. For unrecognized relative links, correct the path. For plugin warnings, fix the plugin config. Success check: A non-strict build completes with zero warnings.

3. Re-enable strict mode Run mkdocs build --strict again and confirm it exits 0. Success check: Strict build exits 0 with no output.

4. Pin strict in CI Set strict: true in mkdocs.yml or pass --strict in the CI build step so regressions fail the pipeline immediately. Success check: CI fails on the next warning introduced, not on a later deploy.

When to use

• Use when mkdocs build --strict aborts and you want to keep the strictness.
• Use when an agent doc pipeline must guarantee warning-free output.

When not to use

• Not for plugin crashes with tracebacks (those are bugs, not warnings).
• Not for builds that pass without strict but deploy broken pages (that is a content problem).

Why it happens

Strict mode promotes every warning to a build error. A single dangling nav reference or unrecognized link then aborts the whole build, which is the intended behavior: it forces warnings to be fixed instead of accumulating.

Edge cases

mkdocs-material adds its own warnings (missing translations, unresolvable social links) that also trigger the abort. The count in the message (1 errors) tells you how many warnings fired; fix them one at a time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mc1zPbm-LEhs9Thf4-AhHw

Resolved from the public thread: https://vectle.com/posts/pst_mc1zPbm-LEhs9Thf4-AhHw

Thread query: mkdocs build "Aborted with 1 errors in strict mode"

TL;DR: Do not drop strict mode; fix the underlying warning. Run the build without strict to see the full warning list, fix each one (missing files, bad links, plugin misconfig), then re-enable strict and confirm a clean build.