squidfunk/mkdocs-material · error · PluginError

Couldn't find author '{id}'

Error message

Couldn't find author '{id}'

What it means

The blog plugin's on_page_markdown assigns authors referenced by a post's metadata to the post. Each author id in page.config.authors must exist in the plugin's authors registry (built from the authors file); otherwise it raises PluginError(f"Couldn't find author '{id}'"). The plugin throws because silent omission would produce posts with missing attribution.

Source

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

                if view in self._resolve_views(self.blog):

                    # If the current view is paginated, use the rendered title
                    # of the original view in case the author set the title in
                    # the page's contents, or it would be overridden with the
                    # one set in mkdocs.yml, leading to inconsistent headings
                    assert isinstance(view, View)
                    if view != page:
                        name = view._title_from_render or view.title
                        return f"# {name}"

            # Nothing more to be done for views
            return

        # Extract and assign authors to post, if enabled
        if self.config.authors:
            for id in page.config.authors:
                if id not in self.authors:
                    raise PluginError(f"Couldn't find author '{id}'")

                # Append to list of authors
                page.authors.append(self.authors[id])

        # Extract settings for excerpts
        separator      = self.config.post_excerpt_separator
        max_authors    = self.config.post_excerpt_max_authors
        max_categories = self.config.post_excerpt_max_categories

        # Ensure presence of separator and throw, if its absent and required -
        # we append the separator to the end of the contents of the post, if it
        # is not already present, so we can remove footnotes or other content
        # from the excerpt without affecting the content of the excerpt
        if separator not in page.markdown:
            if self.config.post_excerpt == "required":
                docs = os.path.relpath(config.docs_dir)
                path = os.path.relpath(page.file.abs_src_path, docs)
                raise PluginError(

View on GitHub (pinned to e2136532f4)

Solutions

1. Add the missing author definition (with all required fields) to the authors file configured for the blog plugin.
2. Fix the author id in the post's front matter to match an existing key in the authors file.
3. Search posts for authors: entries and cross-check every id against the authors file keys.

Example fix

# before (authors.yml has no 'jane')
# post.md front matter
authors:
  - jane

# after (docs/blog/authors.yml)
authors:
  jane:
    name: Jane Doe
    description: Maintainer

import yaml, pathlib
authors = yaml.safe_load(pathlib.Path("docs/blog/authors.yml").read_text()) or {}
used = set()
for post in pathlib.Path("docs/blog/posts").rglob("*.md"):
    fm = post.read_text().split("---")[1]
    used |= set(yaml.safe_load(fm).get("authors", []))
missing = used - set(authors)
assert not missing, f"Author ids missing from authors.yml: {missing}"

def all_authors_defined(ids: list[str], authors: dict) -> bool:
    return all(i in authors for i in ids)

try:
    mkdocs.commands.build.build(config)
except PluginError as e:
    if str(e).startswith("Couldn't find author"):
        print("Add the author to docs/blog/authors.yml or fix front matter:", e)
    else:
        raise

When it happens

Trigger: A post's front matter lists authors: [jane] but no entry with key jane exists in the configured authors file (e.g. docs/blog/authors.yml); author keys were renamed or removed; authors feature enabled with stale metadata.

Common situations: Renaming an author's key in authors.yml without updating posts; typo'd author handles in front matter; copying posts between blogs with different authors files; enabling `authors: true` on a repo where the authors file lacks entries.

Related errors

• Couldn't find '{separator}' in post '{path}' in '{docs}'
• Error reading filter configuration in '{key}': {e}
• Error reading authors file '{path}' in '{docs}': {e}
• Relative path processor not registered
• Unknown shortcode: {type}

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