What causes "Aborted with {len(errors)} configuration errors" in squidfunk/mkdocs-material?

Read the 'Config value X: ...' error lines logged directly above this message and fix each reported config value

squidfunk/mkdocs-material · error · Abort

Aborted with {len(errors)} configuration errors

Error message

Aborted with {len(errors)} configuration errors

What it means

The projects plugin's builder collects configuration validation errors across projects during build. If any project (or the root config) produced config errors, each is logged via log.error and then the build is aborted by raising MkDocs' Abort exception with a count of the errors. This is a deliberate aggregation point: the individual problems were already printed above as 'Config value ...' error lines.

Source

Thrown at src/plugins/projects/builder/__init__.py:320

            log.removeHandler(handler)

    # Return slug, errors and warnings
    return project.slug, errors, warnings

# Print errors and warnings resulting from building a project
def _print(log: Logger, errors: ConfigErrors, warnings: ConfigWarnings):

    # Print warnings
    for value, message in warnings:
        log.warning(f"Config value '{value}': {message}")

    # Print errors
    for value, message in errors:
        log.error(f"Config value '{value}': {message}")

    # Abort if there were errors
    if errors:
        raise Abort(f"Aborted with {len(errors)} configuration errors")

View on GitHub (pinned to e2136532f4)

Solutions

Read the 'Config value X: ...' error lines logged directly above this message and fix each reported config value
Run mkdocs build with -v / --strict on individual sub-projects to isolate which project's config is invalid
Update mkdocs and mkdocs-material and re-check the config schema for deprecated/renamed options

Example fix

# before
site_name: My Site
theme:
  name: materiell
# after
site_name: My Site
theme:
  name: material

Defensive patterns

Strategy: try-catch

Try / catch

try:
    mkdocs build
except SystemExit:
    # scan earlier 'Config value X: ...' error lines and fix each value
    pass

Prevention

Validate every sub-project's mkdocs.yml with mkdocs build --strict in CI per project
Keep configs schema-checked (mkdocs>=1.5 config validation) and avoid undocumented keys
After upgrades, run builds locally before CI to catch renamed/deprecated options

When it happens

Trigger: Running mkdocs build with the projects plugin when one or more project configs fail validation; build() calls _print, which raises Abort(f"Aborted with {len(errors)} configuration errors") whenever the errors list is non-empty.

Common situations: A nested project's mkdocs.yml has an invalid option, wrong type, or deprecated setting; a typo in a config key; schema changes after upgrading mkdocs or the theme; YAML indentation mistakes in sub-project configs.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/0b827d1cc478c342. Report an issue: GitHub.