MkDocs "Aborted with a BuildError" in CI

By Daniel Zoghalchali·Latchkey

MkDocs hit a fatal condition (a strict-mode warning, a failing plugin, or invalid config) and stopped. "Aborted with a BuildError!" is the summary; the real reason is logged just above it.

What this error means

mkdocs build ends with "Aborted with a BuildError!" preceded by an ERROR line describing the actual problem, and the job exits non-zero.

ERROR    -  Config value 'plugins': The "search" plugin is not installed
Aborted with a BuildError!

Common causes

Strict mode escalated a warning

With --strict (or strict: true), a warning such as a broken link or missing nav entry becomes a BuildError.

A plugin failed or is not installed

A plugin listed in plugins is missing or raised during the build, which MkDocs reports as a BuildError.

How to fix it

Read the ERROR line above the abort

1. Scroll up to the ERROR line directly before "Aborted with a BuildError!".
2. Fix what it names (install the plugin, correct the config, fix the link).
3. Re-run the build.

mkdocs build --strict --verbose

Install missing plugins

Add every plugin named in plugins to docs requirements so the build can load them.

# docs/requirements.txt
mkdocs-material
mkdocs-minify-plugin

How to prevent it

• Run mkdocs build --strict locally to catch BuildErrors early.
• Install every configured plugin in CI.
• Use --verbose to see the cause behind the abort.

Frequently asked questions

Related guides

References

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