mkdocs-material build aborted with BuildError on social cards plugin

TL;DR

Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.

Error

BuildError: Social plugin failed to render card for page 'index.md'

Steps

1. Read the chained exception under the BuildError; it usually names a missing library (Pillow, cairosvg) or a missing font. Expected: you know whether it is a dependency or a font problem.
2. Install the missing pieces: pip install "mkdocs-material[imaging]" pulls the Python imaging deps, and your OS package manager provides fonts (e.g. a Noto or DejaVu package). Expected: the import the traceback complained about now succeeds.
3. If you cannot install system packages (locked-down CI), disable the plugin by removing the social entry from the plugins list in mkdocs.yml. Expected: the build no longer invokes card rendering.
4. Rebuild with mkdocs build --strict. Expected: the build completes with no BuildError.

When to use

• The build aborts with BuildError naming the social plugin
• Social cards worked locally but fail in CI or Docker
• You enabled the social plugin and never rendered cards before

When not to use

• Cards render but look wrong (a layout or cache issue, not a build abort)
• The error is about the theme itself not being found
• You do not use the social plugin at all (something else raises BuildError)

Tool compatibility

mkdocs-material 9.x with the built-in social plugin. The imaging extra tracks Pillow and cairosvg versions.

Variant phrasings

BuildError on social cards in a minimal Docker image

Slim images lack fonts and image libraries. Either extend the image or disable the plugin for container builds.

social plugin fails on one page only

That page's title or description likely contains characters the card renderer cannot shape. Simplify the metadata on that page.

Why it happens

The social plugin shells out to an image renderer for every page. Local machines have full font and imaging stacks; CI images do not. The plugin treats a render failure as fatal, so one missing font aborts the entire site build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Thread query: mkdocs-material build aborted with BuildError on social cards plugin

TL;DR: Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.