facebook/docusaurus · error · Error

A highlight range has been given in code block's metastring

Error message

A highlight range has been given in code block's metastring (``` ${metastring}), but no magic comment config is available. Docusaurus applies the first magic comment entry's className for metastring ranges.

What it means

Thrown by `parseCodeLinesFromMetastring` when a Markdown code fence specifies a line-highlight range in its metastring (e.g. ` ```js {1,3-5} `) but the code block's `magicComments` config is empty. Docusaurus applies the first magic-comment entry's className to metastring ranges, so with zero entries it has no class to assign and treats that as a misconfiguration.

Source

Thrown at packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx:232

/**
 * Code lines after applying magic comments or metastring highlight ranges
 */
type ParsedCodeLines = {
  code: string;
  lineClassNames: CodeLineClassNames;
};

function parseCodeLinesFromMetastring(
  code: string,
  {metastring, magicComments}: ParseCodeLinesParam,
): ParsedCodeLines | null {
  // Highlighted lines specified in props: don't parse the content
  if (metastring && metastringLinesRangeRegex.test(metastring)) {
    const linesRange = metastring.match(metastringLinesRangeRegex)!.groups!
      .range!;
    if (magicComments.length === 0) {
      throw new Error(
        `A highlight range has been given in code block's metastring (\`\`\` ${metastring}), but no magic comment config is available. Docusaurus applies the first magic comment entry's className for metastring ranges.`,
      );
    }
    const metastringRangeClassName = magicComments[0]!.className;
    const lines = rangeParser(linesRange)
      .filter((n) => n > 0)
      .map((n) => [n - 1, [metastringRangeClassName]] as [number, string[]]);
    return {lineClassNames: Object.fromEntries(lines), code};
  }
  return null;
}

function parseCodeLinesFromContent(
  code: string,
  params: ParseCodeLinesParam,
): ParsedCodeLines {
  const {language, magicComments} = params;
  if (language === undefined) {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Restore at least one entry in `themeConfig.prism.magicComments` (the default `[{className: 'theme-code-block-highlighted-line', line: 'highlight-next-line', block: {start: 'highlight-start', end: 'highlight-end'}}]`).
2. If you intentionally want no magic comments, remove the `{...}` range from the fence metastring.
3. Use an explicit className by configuring the first magicComments entry to match your CSS.

Example fix

// before — magicComments emptied, but a range is used
```js {1-3}
const a = 1;
```
// docusaurus.config.js
prism: { magicComments: [] }
// after — restore a default entry
prism: {
  magicComments: [
    {className: 'theme-code-block-highlighted-line', line: 'highlight-next-line'}
  ]
}

const hasMagicComments = (themeConfig?.prism?.magicComments?.length ?? 0) > 0;
const fenceHasRange = /\{[\d,-]+\}/.test(fenceMeta);
if (fenceHasRange && !hasMagicComments) {
  // report config error before rendering, do not author ranges
}

When it happens

Trigger: Authoring a fenced code block with a `{1-3}` style range while the prism theme config has set `magicComments: []` (or a preset that empties it). The parser refuses to silently drop the requested highlight.

Common situations: A user disables magic comments (to remove the default `highlight-next-line` behavior) and then authors a metastring range, forgetting that ranges reuse the first magic comment's className; conflicting prism config from a custom theme.

Related errors

• Hook is called outside the <CodeBlockContextProvider>.
• Docusaurus error: Bad <Tabs> child <${badChildTypeName}>: al
• Docusaurus error: Duplicate values "${dup.map((a) => `'${a.v
• Docusaurus error: the <Tabs> component requires at least one
• 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/e184eaa8abdfc7c0. Report an issue: GitHub.