squidfunk/mkdocs-material · error · PluginError

Couldn't find image '{background.image}'

Error message

Couldn't find image '{background.image}'

What it means

The social plugin's background layer accepts an image path to draw behind the card. If the configured background.image file does not exist on disk at render time, _render_background raises PluginError naming the missing image, since the card cannot be composited without it.

Source

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

        )

        # Render background, icon, and typography
        image = self._render_background(layer, image)
        image = self._render_icon(layer, image, config)
        image = self._render_typography(layer, image)

        # Return image with layer
        return image

    # Render layer background
    def _render_background(self, layer: Layer, input: _Image):
        background = layer.background

        # If given, load background image and resize it proportionally to cover
        # the entire area while retaining the aspect ratio of the input image
        if background.image:
            if not os.path.isfile(background.image):
                raise PluginError(f"Couldn't find image '{background.image}'")

            # Open file and convert SVGs to PNGs
            with open(background.image, "rb") as f:
                data = f.read()
                if background.image.endswith(".svg"):
                    data = svg2png(data, output_width = input.width)

            # Resize image to cover entire area
            image = Image.open(BytesIO(data)).convert("RGBA")
            input.alpha_composite(_resize_cover(image, input))

        # If given, fill background color - this is done after the image is
        # loaded to allow for transparent tints. How awesome is that?
        if background.color:
            color = background.color
            if color == "transparent":
                return input

View on GitHub (pinned to e2136532f4)

Solutions

1. Correct the background image path in the social plugin config to the actual file location (prefer a path relative to the project root / docs dir)
2. Verify with ls/test that the file exists in the environment running the build (watch for case sensitivity)
3. Commit or restore the missing image, or remove/comment the background.image option

Example fix

# before
plugins:
  - social:
      cards_layout_options:
        background_image: assests/bg.png
# after
plugins:
  - social:
      cards_layout_options:
        background_image: assets/bg.png

import os, sys
p = "assets/bg.png"
if not os.path.isfile(p):
    sys.exit(f"Background image not found: {p}")

When it happens

Trigger: _render -> _render_background processes a layer whose background.image is set, and os.path.isfile(background.image) returns False — the file does not exist at that exact path in the current working/environment context.

Common situations: Typo in the path in mkdocs.yml; path relative to a different working directory in CI than locally; the image was moved/deleted or never committed to the repo; case-sensitivity mismatch on Linux for paths authored on macOS/Windows.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Error reading filter configuration in '{key}': {e}
• Couldn't find author '{id}'
• Couldn't find '{separator}' in post '{path}' in '{docs}'
• Aborted with {len(errors)} configuration errors
• Required dependencies of "social" plugin not found: {import_

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