facebook/docusaurus · error · Error

To declare blog post authors, use the 'authors' front matter

Error message

To declare blog post authors, use the 'authors' front matter in priority.
Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.

What it means

Thrown by getBlogPostAuthors when a blog post uses both the new 'authors' front matter and any legacy 'author_*' fields (author, author_url, author_image_url, author_title). The plugin refuses to merge them because semantics would be ambiguous; you must pick one style per post.

Source

Thrown at packages/docusaurus-plugin-content-blog/src/authors.ts:166

    return {
      ...author,
      key: author.key ?? null,
      page: author.page ?? null,
      // global author images have already been normalized
      imageURL: normalizeAuthorUrl({author, baseUrl}),
    };
  }
}

export function getBlogPostAuthors(params: AuthorsParam): Author[] {
  const authorLegacy = getFrontMatterAuthorLegacy(params);
  const authors = getFrontMatterAuthors(params);

  if (authorLegacy) {
    // Technically, we could allow mixing legacy/authors front matter, but do we
    // really want to?
    if (authors.length > 0) {
      throw new Error(
        `To declare blog post authors, use the 'authors' front matter in priority.
Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.`,
      );
    }
    return [authorLegacy];
  }

  return authors;
}

/**
 * Group blog posts by author key
 * Blog posts with only inline authors are ignored
 */
export function groupBlogPostsByAuthorKey({
  blogPosts,
  authorsMap,
}: {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Decide on one style per post: prefer 'authors' front matter.
2. Delete all legacy author_* keys from the post's front matter.
3. If you must keep legacy, remove the 'authors' key from that post.

Example fix

---
# before
author: Jane Doe
author_url: https://example.com
authors:
  - name: Jane Doe
---
---
# after
authors:
  - name: Jane Doe
    url: https://example.com
---

const legacyKeys = ['author','author_url','author_image_url','author_title'];
const usesLegacy = legacyKeys.some(k => Object.prototype.hasOwnProperty.call(frontMatter, k));
const usesNew = Array.isArray(frontMatter.authors) || !!frontMatter.authors;
if (usesLegacy && usesNew) throw new Error('Do not mix authors with author_*');

const isLegacyAuthorFm = (fm: Record<string, unknown>) =>
  ['author','author_url','author_image_url','author_title'].some(k => k in fm);

When it happens

Trigger: Front matter contains authors: [...] AND at least one of author / author_url / author_image_url / author_title. getFrontMatterAuthorLegacy returns a value while getFrontMatterAuthors returns a non-empty array.

Common situations: Migrating older blog posts to the new authors syntax without fully removing the legacy keys, or copying a template that already had author_* and then adding authors. CI builds break on the first such post.

Related errors

• Can't reference blog post authors by a key (such as '${key}'
• Duplicate blog post authors were found in blog post path=${b
• The following permalinks are duplicated: ${errorMessage}
• Author socials should be usernames/userIds/handles, or fully
• Processing of blog source file path=${blogSourceFile} failed

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/f9a352379e98b997. Report an issue: GitHub.