facebook/docusaurus · error · Error

Can't reference blog post authors by a key (such as '${key}'

Error message

Can't reference blog post authors by a key (such as '${key}') because no authors map file could be loaded.
Please double-check your blog plugin config (in particular 'authorsMapPath'), ensure the file exists at the configured path, is not empty, and is valid!

What it means

Thrown by getAuthorsMapAuthor when a blog post references an author by key (e.g. `authors: [sebastien]`) but no authors map could be loaded — authorsMap is null or empty. The message points you to the 'authorsMapPath' blog plugin option and requires the file to exist, be non-empty, and be valid.

Source

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

        // support keys, otherwise, a typo in a key would fall back to
        // becoming a name and may end up unnoticed
        return {key: authorInput};
      }
      return {
        ...authorInput,
        socials: normalizeSocials(authorInput.socials ?? {}),
      };
    }

    return Array.isArray(frontMatter.authors)
      ? frontMatter.authors.map(normalizeAuthor)
      : [normalizeAuthor(frontMatter.authors)];
  }

  function getAuthorsMapAuthor(key: string | undefined): Author | undefined {
    if (key) {
      if (!authorsMap || Object.keys(authorsMap).length === 0) {
        throw new Error(`Can't reference blog post authors by a key (such as '${key}') because no authors map file could be loaded.
Please double-check your blog plugin config (in particular 'authorsMapPath'), ensure the file exists at the configured path, is not empty, and is valid!`);
      }
      const author = authorsMap[key];
      if (!author) {
        throw Error(`Blog author with key "${key}" not found in the authors map file.
Valid author keys are:
${Object.keys(authorsMap)
  .map((validKey) => `- ${validKey}`)
  .join('\n')}`);
      }
      return author;
    }
    return undefined;
  }

  function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
    const author = {
      // Author def from authorsMap can be locally overridden by front matter

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Create an authors map file (default authors.yml) at the blog content root with at least one keyed author.
2. Verify the blog plugin option authorsMapPath points to that file (absolute or relative to content path).
3. Validate the YAML parses and contains the keys referenced in front matter.
4. If you did not mean to use keys, switch front matter to inline author objects.

Example fix

// docusaurus.config.js — before
blog: { path: 'blog' }
// after
blog: { path: 'blog', authorsMapPath: 'authors.yml' }
// blog/authors.yml
sebastien:
  name: Sebastien Lorber
  url: https://sebastienlorber.com

import fs from 'fs-extra';
import yaml from 'yaml';
const exists = await fs.pathExists(authorsMapPath);
const parsed = exists ? yaml.parse(await fs.readFile(authorsMapPath, 'utf8')) : null;
if (!parsed || Object.keys(parsed).length === 0) {
  throw new Error(`Authors map missing or empty at ${authorsMapPath}`);
}

const hasAuthorsMap = (m: unknown): m is Record<string, unknown> =>
  !!m && typeof m === 'object' && Object.keys(m as object).length > 0;

When it happens

Trigger: Front matter uses an author key string while authorsMapPath is unset, points to a missing file, or the file failed to parse. Triggered during blog source processing when normalizing authors.

Common situations: You removed or renamed authors.yml, set the wrong path in blog plugin config (authorsMapPath), or the YAML has a syntax error so the map resolves empty. Migration from inline authors to keyed authors without creating the map file.

Related errors

• To declare blog post authors, use the 'authors' front matter
• 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
• You can't use siteConfig.webpack.jsLoader and siteConfig.fut

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