matplotlib/matplotlib · error · ExtensionError

srcset argument "{entry}" is invalid.

Error message

srcset argument "{entry}" is invalid.

What it means

matplotlib's figmpl Sphinx directive builds an HTML <img srcset> for HiDPI figures. Its :srcset: option is a comma-separated list where each entry must be either a bare image path or exactly two space-separated tokens ('path multiplier'). An entry that splits into three or more tokens - or otherwise is not a 1-2 field entry - raises this ExtensionError and aborts the Sphinx build at the directive.

Source

Thrown at lib/matplotlib/sphinxext/figmpl_directive.py:127

        return [image_node]


def _parse_srcsetNodes(st):
    """
    parse srcset...
    """
    entries = st.split(',')
    srcset = {}
    for entry in entries:
        spl = entry.strip().split(' ')
        if len(spl) == 1:
            srcset[0] = spl[0]
        elif len(spl) == 2:
            mult = spl[1][:-1]
            srcset[float(mult)] = spl[0]
        else:
            raise ExtensionError(f'srcset argument "{entry}" is invalid.')
    return srcset


def _copy_images_figmpl(self, node):

    # these will be the temporary place the plot-directive put the images eg:
    # ../../../build/html/plot_directive/users/explain/artists/index-1.png
    if node['srcset']:
        srcset = _parse_srcsetNodes(node['srcset'])
    else:
        srcset = None

    # the rst file's location:  eg /Users/username/matplotlib/doc/users/explain/artists
    docsource = PurePath(self.document['source']).parent

    # get the relpath relative to root:
    srctop = self.builder.srcdir
    rel = relpath(docsource, srctop).replace('.', '').replace(os.sep, '-')

View on GitHub (pinned to b379c1b69e)

Solutions

1. Reformat each entry to 'path multiplier' form, e.g. :srcset: fig-1.png 2.0x
2. Separate multiple entries with commas and remove stray tokens
3. Rename or quote image paths that contain spaces

Example fix

# before (RST)
.. figmpl:: myfig.png
   :srcset: myfig-1.png 2.0x extra-token

# after (RST)
.. figmpl:: myfig.png
   :srcset: myfig-1.png 2.0x

import re

def valid_figmpl_srcset(option: str) -> bool:
    """Each comma-separated entry: bare path, or 'path mult' with a float+x."""
    for entry in option.split(','):
        tokens = entry.strip().split(' ')
        if not 1 <= len(tokens) <= 2:
            return False
        if len(tokens) == 2 and not re.fullmatch(r'[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?x', tokens[1]):
            return False
    return True

assert valid_figmpl_srcset('myfig-1.png 2.0x'), 'fix the :srcset: option'

When it happens

Trigger: Writing :srcset: fig-1.png 2.0x stray under a figmpl directive (three tokens); image paths containing unquoted spaces (each space adds a token); forgetting the comma between two entries so they merge into one multi-token entry.

Common situations: Hand-editing figmpl directives in matplotlib-based docs; copying browser HTML srcset syntax (which allows descriptors and commas per URL, unlike this option); CI doc builds that only fail after the srcset option was added.

Related errors

• srcset argument {entry!r} is invalid.
• plot_srcset option not compatible with single HTML writer
• Invalid value for mathmpl_srcset parameter: {size!r}. Must b
• {arg!r} unknown boolean
• Argument should be None or 'reset' or 'close-figs'

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/2fdbfc26c6efe2e6. Report an issue: GitHub.