squidfunk/mkdocs-material · error · PluginError

Error reading authors file '{path}' in '{docs}': {e}

Error message

Error reading authors file '{path}' in '{docs}':
{e}

What it means

The blog plugin's _resolve_authors() (called from on_config) loads the authors YAML file and calls config.load_dict(yaml.load(...)). If parsing fails — e.g. a YAML syntax error — it wraps the exception into PluginError(f"Error reading authors file '{path}' in '{docs}':\n{e}"). The wrapped message preserves the original parser error so the exact line/syntax problem is visible.

Source

Thrown at src/plugins/blog/plugin.py:502

        # Resolve path relative to docs directory
        docs = os.path.relpath(config.docs_dir)
        file = os.path.join(docs, path)

        # If the authors file does not exist, return here
        config: Authors = Authors()
        if not os.path.isfile(file):
            return config.authors

        # Open file and parse as YAML
        with open(file, encoding = "utf-8-sig") as f:
            config.config_file_path = os.path.abspath(file)
            try:
                config.load_dict(yaml.load(f, SafeLoader) or {})

            # The authors file could not be loaded because of a syntax error,
            # which we display to the author with a nice error message
            except Exception as e:
                raise PluginError(
                    f"Error reading authors file '{path}' in '{docs}':\n"
                    f"{e}"
                )

        # Validate authors and throw if errors occurred
        errors, warnings = config.validate()
        for _, w in warnings:
            log.warning(w)
        for _, e in errors:
            raise PluginError(
                f"Error reading authors file '{path}' in '{docs}':\n"
                f"{e}"
            )

        # Return authors
        return config.authors

    # Resolve views of the given view in pre-order

View on GitHub (pinned to e2136532f4)

Solutions

  1. Read the wrapped exception text after the newline — it pinpoints the YAML line/column; fix that syntax.
  2. Validate the file with a YAML linter or `python -c "import yaml;yaml.safe_load(open('docs/blog/authors.yml'))"`.
  3. Replace tabs with spaces and quote values containing ':' or '#'.
  4. Ensure the path in the plugin config points at the intended file.

Example fix

# before (authors.yml)
authors:
	jane:
	 name: Jane: Doe

# after
authors:
  jane:
    name: "Jane: Doe"
Defensive patterns

Strategy: try-catch

Validate before calling

import yaml
try:
    yaml.safe_load(open("docs/blog/authors.yml"))
except yaml.YAMLError as e:
    raise SystemExit(f"authors.yml invalid YAML:\n{e}")

Type guard

def authors_file_parses(path: str) -> bool:
    import yaml
    try:
        yaml.safe_load(open(path))
        return True
    except yaml.YAMLError:
        return False

Try / catch

try:
    mkdocs.commands.build.build(config)
except PluginError as e:
    if str(e).startswith("Error reading authors file"):
        detail = str(e).split("\n", 1)[1]
        print("Fix YAML syntax in authors file:", detail)
    else:
        raise

Prevention

When it happens

Trigger: Authors file (e.g. docs/blog/authors.yml) contains invalid YAML: bad indentation, unquoted special characters, tabs, missing colon, duplicate keys that yaml.SafeLoader rejects at load time.

Common situations: Hand-editing authors.yml and breaking indentation; pasting authors with names containing colons or hashes unquoted; saving with tabs instead of spaces; empty/malformed file.

Related errors

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