What causes "Couldn't find image '{background.image}'" in squidfunk/mkdocs-material?

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)

squidfunk/mkdocs-material · error · PluginError

Couldn't find 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.

Solutions

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)
Verify with ls/test that the file exists in the environment running the build (watch for case sensitivity)
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

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use paths relative to the repo root and resolve them the same way in CI and locally
Commit background images to the repo; never reference untracked local files
Watch case sensitivity: match filenames exactly for Linux CI

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

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

Appendix: 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)