{"record":{"id":"b69587add47d1e3c","repo":"squidfunk/mkdocs-material","slug":"cairosvg-python-module-is-installed-but-it-cras","errorCode":null,"errorMessage":"\"cairosvg\" Python module is installed, but it crashed with:\n{cairosvg_error}\n\n--> Check out the troubleshooting guide: https://t.ly/MfX6u","messagePattern":"\"cairosvg\" Python module is installed, but it crashed with:\n(.+?)\n\n--> Check out the troubleshooting guide: https://t\\.ly/MfX6u","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":415,"sourceCode":"        # to the caller, so he can decide what to do with the error. The caller\n        # can treat this as a warning or an error to abort the build.\n        if import_errors:\n            # docs = os.path.relpath(config.docs_dir)\n            # path = os.path.relpath(page.file.abs_src_path, docs)\n            # raise PluginError(\n            #     f\"Couldn't render card for '{path}' in '{docs}': install \"\n            #     f\"required dependencies – pip install 'mkdocs-material[imaging]'\"\n            # )\n            # @todo improve formatting of error handling\n            raise PluginError(\n                \"Required dependencies of \\\"social\\\" plugin not found:\\n\"\n                + str(\"\\n\".join(map(lambda x: \"- \" + x, import_errors)))\n                + \"\\n\\n\"\n                + \"--> Install with: pip install \\\"mkdocs-material[imaging]\\\"\"\n            )\n        if cairosvg_error:\n            # @todo improve formatting of error handling\n            raise PluginError(\n                \"\\\"cairosvg\\\" Python module is installed, but it crashed with:\\n\"\n                + cairosvg_error\n                + \"\\n\\n\"\n                + \"--> Check out the troubleshooting guide: https://t.ly/MfX6u\"\n            )\n\n        # Spawn concurrent jobs to render layers - we only need to render layers\n        # that we haven't already dispatched, reducing work by deduplication\n        for h, layer in layers.items():\n            sentinel = Future()\n\n            # We need to use a hack here to avoid locking the thread pool while\n            # we check if the layer was already dispatched. If we don't do this,\n            # layers might be dispatched multiple times. The trick is to use a\n            # sentinel value to check if the layer was already dispatched.\n            if sentinel == self.card_layer_pool_jobs.setdefault(h, sentinel):\n                self.card_layer_pool_jobs[h] = self.card_layer_pool.submit(\n                    self._render, layer, page, config","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L397-L433","documentation":"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.","triggerScenarios":"_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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"python - <<'EOF'\nimport cairosvg\ncairosvg.svg2png(bytestring=b\"<svg xmlns='http://www.w3.org/2000/svg' width='4' height='4'/>\")\nprint(\"cairosvg OK\")\nEOF","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs build\nexcept SystemExit:\n    # follow https://t.ly/MfX6u; reinstall cairosvg + native libs\n    pass","preventionTips":["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"],"tags":["cairosvg","native-dependency","social-plugin","mkdocs","environment"],"backgroundTag":"native-library-crash","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}