facebook/docusaurus · error · Error

Unexpected "reportingSeverity" value: ${reportingSeverity}.

Error message

Unexpected "reportingSeverity" value: ${reportingSeverity}.

What it means

Thrown by logger.report() in @docusaurus/logger when the reportingSeverity argument is not one of the known keys: 'ignore', 'log', 'warn', 'throw'. report() looks up a handler in a fixed object and rejects unknown values rather than silently no-op'ing. This normally reflects a config typo in onDuplicateRoutes / onBrokenLinks / onBrokenMarkdownLinks or a programmer error passing an unvalidated string.

Source

Thrown at packages/docusaurus-logger/src/logger.ts:170

 * - `throw`: aborts the process, throws the error.
 *
 * Since the logger doesn't have logging level filters yet, these severities
 * mostly just differ by their colors.
 *
 * @throws In addition to throwing when `reportingSeverity === "throw"`, this
 * function also throws if `reportingSeverity` is not one of the above.
 */
function report(reportingSeverity: ReportingSeverity): typeof success {
  const reportingMethods = {
    ignore: () => {},
    log: info,
    warn,
    throw: throwError,
  };
  if (
    !Object.prototype.hasOwnProperty.call(reportingMethods, reportingSeverity)
  ) {
    throw new Error(
      `Unexpected "reportingSeverity" value: ${reportingSeverity}.`,
    );
  }
  return reportingMethods[reportingSeverity];
}

const logger = {
  red: (msg: string | number): string => chalk.red(msg),
  yellow: (msg: string | number): string => chalk.yellow(msg),
  green: (msg: string | number): string => chalk.green(msg),
  cyan: (msg: string | number): string => chalk.cyan(msg),
  bold: (msg: string | number): string => chalk.bold(msg),
  dim: (msg: string | number): string => chalk.dim(msg),
  path,
  url,
  name,
  code,
  subdue,

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Set the severity to one of: 'ignore' | 'log' | 'warn' | 'throw'.
2. Search docusaurus.config for onBrokenLinks, onBrokenMarkdownLinks, onDuplicateRoutes and fix each value.
3. If the value comes from a plugin option, validate it against the ReportingSeverity union before forwarding to logger.report.

Example fix

// before
onBrokenLinks: 'error',
// after
onBrokenLinks: 'throw',

import type {ReportingSeverity} from '@docusaurus/types';
const SEVERITIES: ReportingSeverity[] = ['ignore', 'log', 'warn', 'throw'];
function assertSeverity(v: string): asserts v is ReportingSeverity {
  if (!SEVERITIES.includes(v as ReportingSeverity)) {
    throw new Error(`Unexpected reportingSeverity value: ${v}`);
  }
}

import type {ReportingSeverity} from '@docusaurus/types';
const isReportingSeverity = (v: unknown): v is ReportingSeverity =>
  v === 'ignore' || v === 'log' || v === 'warn' || v === 'throw';

When it happens

Trigger: Setting onBrokenLinks (or onDuplicateRoutes, onBrokenMarkdownLinks) in docusaurus.config to a value like 'error', 'raise', 'warn ' (trailing space), or any string other than the four allowed. report() is then called with that value and throws.

Common situations: Intuitively writing onBrokenLinks: 'error' instead of 'throw'; copying a config between Docusaurus versions where severity names changed; a plugin forwarding a user-supplied severity string without validation.

Related errors

• ${JSON.stringify(redirect)} => Validation error: ${error.mes
• Invalid sidebars file. The document with id "${docId}" was u
• Invalid module path of type "name=${typeof modulePath}" with
• Swizzle config does not match expected schema: ${result.erro
• Theme ${themeName} not found

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