{"record":{"id":"e2454b4595240bca","repo":"squidfunk/mkdocs-material","slug":"couldn-t-find-image-background-image","errorCode":null,"errorMessage":"Couldn't find image '{background.image}'","messagePattern":"Couldn't find image '(.+?)'","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":487,"sourceCode":"        )\n\n        # Render background, icon, and typography\n        image = self._render_background(layer, image)\n        image = self._render_icon(layer, image, config)\n        image = self._render_typography(layer, image)\n\n        # Return image with layer\n        return image\n\n    # Render layer background\n    def _render_background(self, layer: Layer, input: _Image):\n        background = layer.background\n\n        # If given, load background image and resize it proportionally to cover\n        # the entire area while retaining the aspect ratio of the input image\n        if background.image:\n            if not os.path.isfile(background.image):\n                raise PluginError(f\"Couldn't find image '{background.image}'\")\n\n            # Open file and convert SVGs to PNGs\n            with open(background.image, \"rb\") as f:\n                data = f.read()\n                if background.image.endswith(\".svg\"):\n                    data = svg2png(data, output_width = input.width)\n\n            # Resize image to cover entire area\n            image = Image.open(BytesIO(data)).convert(\"RGBA\")\n            input.alpha_composite(_resize_cover(image, input))\n\n        # If given, fill background color - this is done after the image is\n        # loaded to allow for transparent tints. How awesome is that?\n        if background.color:\n            color = background.color\n            if color == \"transparent\":\n                return input\n","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L469-L505","documentation":"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.","triggerScenarios":"_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.","commonSituations":"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.","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"],"exampleFix":"# before\nplugins:\n  - social:\n      cards_layout_options:\n        background_image: assests/bg.png\n# after\nplugins:\n  - social:\n      cards_layout_options:\n        background_image: assets/bg.png","handlingStrategy":"validation","validationCode":"import os, sys\np = \"assets/bg.png\"\nif not os.path.isfile(p):\n    sys.exit(f\"Background image not found: {p}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["social-plugin","file-not-found","mkdocs","configuration","image"],"backgroundTag":"resource-not-found","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}