{"record":{"id":"e184eaa8abdfc7c0","repo":"facebook/docusaurus","slug":"a-highlight-range-has-been-given-in-code-block-s-m","errorCode":null,"errorMessage":"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.","messagePattern":"A highlight range has been given in code block's metastring \\(``` (.+?)\\), but no magic comment config is available\\. Docusaurus applies the first magic comment entry's className for metastring ranges\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx","lineNumber":232,"sourceCode":"\n/**\n * Code lines after applying magic comments or metastring highlight ranges\n */\ntype ParsedCodeLines = {\n  code: string;\n  lineClassNames: CodeLineClassNames;\n};\n\nfunction parseCodeLinesFromMetastring(\n  code: string,\n  {metastring, magicComments}: ParseCodeLinesParam,\n): ParsedCodeLines | null {\n  // Highlighted lines specified in props: don't parse the content\n  if (metastring && metastringLinesRangeRegex.test(metastring)) {\n    const linesRange = metastring.match(metastringLinesRangeRegex)!.groups!\n      .range!;\n    if (magicComments.length === 0) {\n      throw new Error(\n        `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.`,\n      );\n    }\n    const metastringRangeClassName = magicComments[0]!.className;\n    const lines = rangeParser(linesRange)\n      .filter((n) => n > 0)\n      .map((n) => [n - 1, [metastringRangeClassName]] as [number, string[]]);\n    return {lineClassNames: Object.fromEntries(lines), code};\n  }\n  return null;\n}\n\nfunction parseCodeLinesFromContent(\n  code: string,\n  params: ParseCodeLinesParam,\n): ParsedCodeLines {\n  const {language, magicComments} = params;\n  if (language === undefined) {","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-theme-common/src/utils/codeBlockUtils.tsx#L214-L250","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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'}}]`).","If you intentionally want no magic comments, remove the `{...}` range from the fence metastring.","Use an explicit className by configuring the first magicComments entry to match your CSS."],"exampleFix":"// before — magicComments emptied, but a range is used\n```js {1-3}\nconst a = 1;\n```\n// docusaurus.config.js\nprism: { magicComments: [] }\n// after — restore a default entry\nprism: {\n  magicComments: [\n    {className: 'theme-code-block-highlighted-line', line: 'highlight-next-line'}\n  ]\n}","handlingStrategy":"validation","validationCode":"const hasMagicComments = (themeConfig?.prism?.magicComments?.length ?? 0) > 0;\nconst fenceHasRange = /\\{[\\d,-]+\\}/.test(fenceMeta);\nif (fenceHasRange && !hasMagicComments) {\n  // report config error before rendering, do not author ranges\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep at least one entry in `prism.magicComments` when using metastring ranges.","If disabling magic comments, do not author `{...}` ranges.","Add a CI check that scans fences for ranges when magicComments is empty."],"tags":["mdx","code-block","prism","config","theme-common"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}