squidfunk/mkdocs-material · error · PluginError

"cairosvg" Python module is installed, but it crashed with:

Error message

"cairosvg" Python module is installed, but it crashed with:
{cairosvg_error}

--> Check out the troubleshooting guide: https://t.ly/MfX6u

What it means

CairoSVG is present but crashed while being exercised (or at import/first use), so the social plugin cannot rasterize SVG assets for social cards. The plugin raises PluginError embedding the underlying cairosvg error text and a link to the troubleshooting guide, because a broken native cairo setup cannot be fixed from within the plugin.

Source

Thrown at src/plugins/social/plugin.py:415

        # to the caller, so he can decide what to do with the error. The caller
        # can treat this as a warning or an error to abort the build.
        if import_errors:
            # docs = os.path.relpath(config.docs_dir)
            # path = os.path.relpath(page.file.abs_src_path, docs)
            # raise PluginError(
            #     f"Couldn't render card for '{path}' in '{docs}': install "
            #     f"required dependencies – pip install 'mkdocs-material[imaging]'"
            # )
            # @todo improve formatting of error handling
            raise PluginError(
                "Required dependencies of \"social\" plugin not found:\n"
                + str("\n".join(map(lambda x: "- " + x, import_errors)))
                + "\n\n"
                + "--> Install with: pip install \"mkdocs-material[imaging]\""
            )
        if cairosvg_error:
            # @todo improve formatting of error handling
            raise PluginError(
                "\"cairosvg\" Python module is installed, but it crashed with:\n"
                + cairosvg_error
                + "\n\n"
                + "--> Check out the troubleshooting guide: https://t.ly/MfX6u"
            )

        # Spawn concurrent jobs to render layers - we only need to render layers
        # that we haven't already dispatched, reducing work by deduplication
        for h, layer in layers.items():
            sentinel = Future()

            # We need to use a hack here to avoid locking the thread pool while
            # we check if the layer was already dispatched. If we don't do this,
            # layers might be dispatched multiple times. The trick is to use a
            # sentinel value to check if the layer was already dispatched.
            if sentinel == self.card_layer_pool_jobs.setdefault(h, sentinel):
                self.card_layer_pool_jobs[h] = self.card_layer_pool.submit(
                    self._render, layer, page, config

View on GitHub (pinned to e2136532f4)

Solutions

Open the troubleshooting guide (https://t.ly/MfX6u) and follow the cairo setup steps for your OS
Reinstall cairosvg and native cairo: pip install --force-reinstall cairosvg plus apt/yum install of libcairo2/pango packages
Inside Docker use an image with the native libs (or apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 fontconfig) and verify with python -c 'import cairosvg; cairosvg.svg2png(b"<svg/>"+b"")'
If the crash persists, disable the social plugin or pre-render assets without cairo

Defensive patterns

Strategy: validation

Validate before calling

python - <<'EOF'
import cairosvg
cairosvg.svg2png(bytestring=b"<svg xmlns='http://www.w3.org/2000/svg' width='4' height='4'/>")
print("cairosvg OK")
EOF

Try / catch

try:
    mkdocs build
except SystemExit:
    # follow https://t.ly/MfX6u; reinstall cairosvg + native libs
    pass

Prevention

Smoke-test cairosvg rendering in CI before running mkdocs build
Use maintained base images with cairo/pango/fontconfig preinstalled
Pin cairosvg and native library versions; avoid mixing system and pip-installed cairo

When it happens

Trigger: _generate detects cairosvg_error is truthy — the cairosvg module imported but its invocation failed, typically due to broken or mismatched native cairo/pango libraries, or an incompatible cairosvg/fontconfig setup in the environment.

Common situations: Mixing pip-installed cairosvg wheels with system cairo of the wrong version; missing fontconfig/fonts in slim Docker images; corrupt libcairo after OS upgrade; Windows without the GTK runtime cairosvg needs.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/b69587add47d1e3c. Report an issue: GitHub.