{"record":{"id":"3ae19a80b0ed0d10","repo":"squidfunk/mkdocs-material","slug":"error-reading-authors-file-path-in-docs","errorCode":null,"errorMessage":"Error reading authors file '{path}' in '{docs}':\n{e}","messagePattern":"Error reading authors file '(.+?)' in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/blog/plugin.py","lineNumber":502,"sourceCode":"        # Resolve path relative to docs directory\n        docs = os.path.relpath(config.docs_dir)\n        file = os.path.join(docs, path)\n\n        # If the authors file does not exist, return here\n        config: Authors = Authors()\n        if not os.path.isfile(file):\n            return config.authors\n\n        # Open file and parse as YAML\n        with open(file, encoding = \"utf-8-sig\") as f:\n            config.config_file_path = os.path.abspath(file)\n            try:\n                config.load_dict(yaml.load(f, SafeLoader) or {})\n\n            # The authors file could not be loaded because of a syntax error,\n            # which we display to the author with a nice error message\n            except Exception as e:\n                raise PluginError(\n                    f\"Error reading authors file '{path}' in '{docs}':\\n\"\n                    f\"{e}\"\n                )\n\n        # Validate authors and throw if errors occurred\n        errors, warnings = config.validate()\n        for _, w in warnings:\n            log.warning(w)\n        for _, e in errors:\n            raise PluginError(\n                f\"Error reading authors file '{path}' in '{docs}':\\n\"\n                f\"{e}\"\n            )\n\n        # Return authors\n        return config.authors\n\n    # Resolve views of the given view in pre-order","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/blog/plugin.py#L484-L520","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped exception text after the newline — it pinpoints the YAML line/column; fix that syntax.","Validate the file with a YAML linter or `python -c \"import yaml;yaml.safe_load(open('docs/blog/authors.yml'))\"`.","Replace tabs with spaces and quote values containing ':' or '#'.","Ensure the path in the plugin config points at the intended file."],"exampleFix":"# before (authors.yml)\nauthors:\n\tjane:\n\t name: Jane: Doe\n\n# after\nauthors:\n  jane:\n    name: \"Jane: Doe\"","handlingStrategy":"try-catch","validationCode":"import yaml\ntry:\n    yaml.safe_load(open(\"docs/blog/authors.yml\"))\nexcept yaml.YAMLError as e:\n    raise SystemExit(f\"authors.yml invalid YAML:\\n{e}\")","typeGuard":"def authors_file_parses(path: str) -> bool:\n    import yaml\n    try:\n        yaml.safe_load(open(path))\n        return True\n    except yaml.YAMLError:\n        return False","tryCatchPattern":"try:\n    mkdocs.commands.build.build(config)\nexcept PluginError as e:\n    if str(e).startswith(\"Error reading authors file\"):\n        detail = str(e).split(\"\\n\", 1)[1]\n        print(\"Fix YAML syntax in authors file:\", detail)\n    else:\n        raise","preventionTips":["Use spaces, never tabs, in authors.yml; enforce with a YAML linter/formatter.","Quote author names and descriptions containing ':' or '#'.","Run mkdocs serve after every authors.yml edit before committing.","Add YAML schema validation for the authors file in CI."],"tags":["python","mkdocs","yaml","blog-plugin","parse-error"],"backgroundTag":"yaml-syntax-error","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}