{"record":{"id":"ba320dd5b80cc117","repo":"squidfunk/mkdocs-material","slug":"couldn-t-find-icon-name","errorCode":null,"errorMessage":"Couldn't find icon '{name}'","messagePattern":"Couldn't find icon '(.+?)'","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":823,"sourceCode":"    # Resolve icon with given name - this function searches for the icon in all\n    # known theme directories, including custom directories specified by the\n    # author, which allows for using custom icons in cards. If the icon cannot\n    # be resolved, the plugin must abort with an error.\n    def _resolve_icon(self, name: str, config: MkDocsConfig):\n        for base in config.theme.dirs:\n            path = os.path.join(base, \".icons\", f\"{name}.svg\")\n            path = os.path.normpath(path)\n\n            # Skip if icon does not exist and try next directory\n            if not os.path.isfile(path):\n                continue\n\n            # Open and return icon\n            with open(path, encoding = \"utf-8\") as f:\n                return f.read()\n\n        # Abort if the icon could not be resolved\n        raise PluginError(f\"Couldn't find icon '{name}'\")\n\n    # Resolve font family with specific style - if we haven't already done it,\n    # the font family is first downloaded from Google Fonts and the styles are\n    # saved to the cache directory. If the font cannot be resolved, the plugin\n    # must abort with an error.\n    def _resolve_font(self, family: str, style: str, variant = \"\"):\n        path = os.path.join(self.config.cache_dir, \"fonts\", family)\n\n        # Fetch font family, if it hasn't been fetched yet - we use a lock to\n        # synchronize access, so the font is not downloaded multiple times, but\n        # all other threads wait for the font being available. This is also why\n        # we need the double path check, which makes sure that we only use the\n        # lock when we actually need to download a font that doesn't exist. If\n        # we already downloaded it, we don't want to block at all.\n        if not os.path.isdir(path):\n            with self.lock:\n                if not os.path.isdir(path):\n                    self._fetch_font_from_google_fonts(family)","sourceCodeStart":805,"sourceCodeEnd":841,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L805-L841","documentation":"`_resolve_icon` searches all known theme directories (including custom icon directories) for an SVG file with the given name and returns its contents. When no file matches, it throws this PluginError, because social card rendering cannot proceed without the icon asset.","triggerScenarios":"`social.cards_icon` page meta or a card layout references an icon name that doesn't exist under `templates/.icons`, custom theme icon dirs, or `icon` paths in mkdocs.yml; icon name missing its path prefix (e.g. `fontawesome/brands/github`); icon file deleted or not bundled with the theme version.","commonSituations":"Using a Material Symbols or simple-icons name without the required path prefix; icon renamed between mkdocs-material releases; custom icon directory not registered in theme config; typo in the icon slug.","solutions":["Use the fully qualified icon path as it exists under the theme's `.icons` tree, e.g. `fontawesome/brands/github` or `material/github`.","Verify the icon file exists in `.icons/` within the theme or your custom directory (`find .venv -path '*.icons*' -name 'github*').","Register custom icon directories via the theme's icon configuration if using your own SVGs.","Upgrade or pin mkdocs-material if the icon set changed between versions."],"exampleFix":"# before (page meta)\nsocial:\n  cards_icon: github\n\n# after\nsocial:\n  cards_icon: fontawesome/brands/github","handlingStrategy":"validation","validationCode":"import pathlib, mkdocs\n# check icon exists in any theme .icons dir before referencing it\nicons_roots = [pathlib.Path(mkdocs.__file__).parent / 'themes' / 'material' / '.icons']\nassert any((root / f\"{icon_name}.svg\").is_file() for root in icons_roots), f\"icon {icon_name} not found\"","typeGuard":null,"tryCatchPattern":"from mkdocs.exceptions import PluginError\ntry:\n    svg = plugin._resolve_icon(name)\nexcept PluginError as e:\n    log.warning(f\"Icon missing, skipping: {e}\")\n    svg = None","preventionTips":["Always use the fully qualified icon path (e.g. fontawesome/brands/github)","Verify icon names against the bundled `.icons` directory of your material version","Register custom icon directories in the theme config when using own SVGs"],"tags":["mkdocs-material","social-plugin","icons","missing-asset"],"backgroundTag":"missing-asset-file","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}