facebook/docusaurus · error · Error

Author socials should be usernames/userIds/handles, or fully

Error message

Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
Social platform '${platform}' has illegal value '${value}'

What it means

Thrown by normalizeSocialEntry when an author social value is not a string (e.g. a number, boolean, or null parsed from YAML). The first guard in the function checks typeof value !== 'string'. The message names the offending platform key and value.

Source

Thrown at packages/docusaurus-plugin-content-blog/src/authorsSocials.ts:58

  twitter: (handle: string) => `https://twitter.com/${handle}`,
  github: (handle: string) => `https://github.com/${handle}`,
  linkedin: (handle: string) => `https://www.linkedin.com/in/${handle}/`,
  stackoverflow: (userId: string) =>
    `https://stackoverflow.com/users/${userId}`,
  bluesky: (handle: string) => `https://bsky.app/profile/${handle}`,
  instagram: (handle: string) => `https://www.instagram.com/${handle}`,
  threads: (handle: string) => `https://www.threads.net/@${handle}`,
  mastodon: (handle: string) => `https://mastodon.social/@${handle}`, // can be in format user@other.server and it will redirect if needed
  twitch: (handle: string) => `https://twitch.tv/${handle}`,
  youtube: (handle: string) => `https://youtube.com/@${handle}`, // https://support.google.com/youtube/answer/6180214?hl=en
  email: (email: string) => `mailto:${email}`,
};

type SocialEntry = [string, string];

function normalizeSocialEntry([platform, value]: SocialEntry): SocialEntry {
  if (typeof value !== 'string') {
    throw new Error(
      `Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
Social platform '${platform}' has illegal value '${value}'`,
    );
  }
  const isAbsoluteUrl =
    value.startsWith('http://') ||
    value.startsWith('https://') ||
    value.startsWith('mailto:');
  if (isAbsoluteUrl) {
    return [platform, value];
  } else if (value.includes('/')) {
    throw new Error(
      `Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
Social platform '${platform}' has illegal value '${value}'`,
    );
  }
  const normalizer = PredefinedPlatformNormalizers[platform.toLowerCase()];
  if (normalizer && !isAbsoluteUrl) {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Quote any purely-numeric handles in your YAML (e.g. `stackoverflow: "82609"`).
2. Remove null/empty social entries rather than leaving them blank.
3. Ensure each social value is a single string scalar, not a list or map.

Example fix

# before
stackoverflow: 82609
twitter:
# after
stackoverflow: "82609"
# (remove the empty twitter line)

for (const [platform, value] of Object.entries(socials)) {
  if (typeof value !== 'string') {
    throw new Error(`Social '${platform}' must be a string, got ${typeof value}`);
  }
}

const isStringSocials = (s: Record<string, unknown>): s is Record<string, string> =>
  Object.values(s).every(v => typeof v === 'string');

When it happens

Trigger: An author's socials map has a non-string value, such as `stackoverflow: 82609` without quote-wrapping when Joi's coercion is bypassed, or `twitter: null`. Triggered while normalizing an author's socials during blog post processing.

Common situations: YAML auto-parses unquoted numbers/booleans, so `github: 12345` becomes a number. Authors map or front matter with a missing/null value or a list where a scalar is expected.

Related errors

• The following permalinks are duplicated: ${errorMessage}
• Can't reference blog post authors by a key (such as '${key}'
• To declare blog post authors, use the 'authors' front matter
• Duplicate blog post authors were found in blog post path=${b
• Duplicate permalinks found in tags file: ${duplicateList}

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