{"record":{"id":"4b4752346ac4b35b","repo":"matplotlib/matplotlib","slug":"the-filename-prefix-output-base-r-is-used-multip-4b4752","errorCode":null,"errorMessage":"The filename-prefix {output_base!r} is used multipletimes (it is also used in {env.doc2path(d)}).","messagePattern":"The filename-prefix (.+?) is used multipletimes \\(it is also used in (.+?)\\)\\.","errorType":"exception","errorClass":"PlotError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/sphinxext/plot_directive.py","lineNumber":668,"sourceCode":"        else:\n            raise ExtensionError(f'srcset argument {entry!r} is invalid.')\n    return srcset\n\n\ndef check_output_base_name(env, output_base):\n    docname = env.docname\n\n    if '.' in output_base or '/' in output_base or '\\\\' in output_base:\n        raise PlotError(\n            f\"The filename-prefix '{output_base}' is invalid. \"\n            f\"It must not contain dots or slashes.\")\n\n    for d in env.mpl_plot_image_basenames:\n        if output_base in env.mpl_plot_image_basenames[d]:\n            if d == docname:\n                raise PlotError(\n                    f\"The filename-prefix {output_base!r} is used multiple times.\")\n            raise PlotError(f\"The filename-prefix {output_base!r} is used multiple\"\n                            f\"times (it is also used in {env.doc2path(d)}).\")\n\n    env.mpl_plot_image_basenames[docname].add(output_base)\n\n\ndef render_figures(code, code_path, output_dir, output_base, context,\n                   function_name, config, context_reset=False,\n                   close_figs=False,\n                   code_includes=None):\n    \"\"\"\n    Run a pyplot script and save the images in *output_dir*.\n\n    Save the images under *output_dir* with file names derived from\n    *output_base*\n    \"\"\"\n\n    if function_name is not None:\n        output_base = f'{output_base}_{function_name}'","sourceCodeStart":650,"sourceCodeEnd":686,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/sphinxext/plot_directive.py#L650-L686","documentation":"Same uniqueness rule as the in-document check, but this branch fires when the filename-prefix was already registered by a different document; the message names the other file via env.doc2path(d). Because all generated plot images land in a shared build location, identical prefixes across documents would overwrite each other, so the build stops. Note the message text runs 'multipletimes' together (missing space) - useful when grepping build logs.","triggerScenarios":"Two .rst files (e.g. a users guide and an API tutorial) each containing a .. plot:: with the same :filename-prefix: plot-; shared RST include snippets that carry a hardcoded prefix and are included from several pages.","commonSituations":"Docs split into chapters that reuse example templates; shared includes with fixed prefixes; prefixes that were unique until a new page copied an existing block.","solutions":["Make prefixes globally unique - include the doc slug: :filename-prefix: users-plot-","Prefer automatic naming by omitting :filename-prefix:","Audit the sources: grep -rn 'filename-prefix:' docs/ and de-duplicate"],"exampleFix":"# before (two different .rst files)\n:filename-prefix: plot-   # in doc_a.rst and doc_b.rst -> collision\n\n# after\ndoc_a.rst: :filename-prefix: intro-plot-\ndoc_b.rst: :filename-prefix: api-plot-","handlingStrategy":"validation","validationCode":"# pre-build check: no prefix reused across documents\nimport glob, re\nfrom collections import Counter\n\ncounts = Counter()\nfor path in glob.glob('docs/**/*.rst', recursive=True):\n    text = open(path).read()\n    for m in re.finditer(r':filename-prefix:\\s*(\\S+):', text):\n        counts[m.group(1)] += 1\ndups = [p for p, n in counts.items() if n > 1]\nassert not dups, f'filename-prefix values used more than once: {dups}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Namespace prefixes by document slug (users-plot-, api-plot-) so they are globally unique","Be careful with shared RST includes that hardcode a filename-prefix and are included from several pages","Run a duplicate-prefix grep in CI before sphinx-build: grep -rn 'filename-prefix:' docs/"],"tags":["matplotlib","sphinx","plot-directive","filename-prefix","duplicate","cross-document","ploterror"],"backgroundTag":"duplicate-filename-prefix","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}