Exceptions¶

All errors from resvg_py surface as ValueError. Below is every scenario, the exact message, and how to avoid it.

Invalid SVG input¶

ValueError: 'svg_string' is empty or 'svg_path' contains empty invalid svg

Raised when:

svg_string is None, "", or only whitespace.
svg_path points to a file that is empty, missing, or contains no valid SVG.
A .svgz file fails to decompress.

Tip

Validate your SVG with an XML parser or xmllint before passing it to svg_to_bytes.

Invalid rendering option values¶

Each rendering parameter accepts a fixed set of values. Passing anything else raises:

ValueError: The value of 'shape_rendering' must be one of ...

Valid values per parameter¶
Parameter	Accepted values
`shape_rendering`	`"optimize_speed"`, `"crisp_edges"`, `"geometric_precision"`
`text_rendering`	`"optimize_speed"`, `"optimize_legibility"`, `"geometric_precision"`
`image_rendering`	`"optimize_quality"`, `"optimize_speed"`

Warning

Example – wrong value

>>> resvg_py.svg_to_bytes(svg_string=svg, shape_rendering="best")
ValueError: The value of 'shape_rendering' must be one of
'optimize_speed','crisp_edges','geometric_precision'.
It is currently 'best'

Background color parse error¶

ValueError: Error background: <svgtypes error details>

Raised when the background string cannot be parsed as a CSS color by the svgtypes crate.

Warning

Example – invalid color

>>> resvg_py.svg_to_bytes(svg_string=svg, background="not-a-color")
ValueError: Error background: ...

Rendering / processing errors¶

Any failure during XML parsing, SVG tree construction, pixmap creation, or PNG encoding is raised as ValueError with the underlying Rust error message.

Common causes:

Malformed XML (unclosed tags, invalid namespaces)
Dimensions that are zero or exceed the platform’s maximum pixmap size
Out-of-memory during PNG encoding

ValueError: <specific error message from the resvg library>

Danger

Extremely large width / height or zoom values can cause an OutOfMemory panic at the Rust level. Keep dimensions under 32767 pixels per side.