squidfunk/mkdocs-material · error · PluginError

Couldn't find icon '{name}'

Error message

Couldn't find icon '{name}'

What it means

`_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.

Source

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

    # Resolve icon with given name - this function searches for the icon in all
    # known theme directories, including custom directories specified by the
    # author, which allows for using custom icons in cards. If the icon cannot
    # be resolved, the plugin must abort with an error.
    def _resolve_icon(self, name: str, config: MkDocsConfig):
        for base in config.theme.dirs:
            path = os.path.join(base, ".icons", f"{name}.svg")
            path = os.path.normpath(path)

            # Skip if icon does not exist and try next directory
            if not os.path.isfile(path):
                continue

            # Open and return icon
            with open(path, encoding = "utf-8") as f:
                return f.read()

        # Abort if the icon could not be resolved
        raise PluginError(f"Couldn't find icon '{name}'")

    # Resolve font family with specific style - if we haven't already done it,
    # the font family is first downloaded from Google Fonts and the styles are
    # saved to the cache directory. If the font cannot be resolved, the plugin
    # must abort with an error.
    def _resolve_font(self, family: str, style: str, variant = ""):
        path = os.path.join(self.config.cache_dir, "fonts", family)

        # Fetch font family, if it hasn't been fetched yet - we use a lock to
        # synchronize access, so the font is not downloaded multiple times, but
        # all other threads wait for the font being available. This is also why
        # we need the double path check, which makes sure that we only use the
        # lock when we actually need to download a font that doesn't exist. If
        # we already downloaded it, we don't want to block at all.
        if not os.path.isdir(path):
            with self.lock:
                if not os.path.isdir(path):
                    self._fetch_font_from_google_fonts(family)

View on GitHub (pinned to e2136532f4)

Solutions

1. Use the fully qualified icon path as it exists under the theme's `.icons` tree, e.g. `fontawesome/brands/github` or `material/github`.
2. Verify the icon file exists in `.icons/` within the theme or your custom directory (`find .venv -path '*.icons*' -name 'github*').
3. Register custom icon directories via the theme's icon configuration if using your own SVGs.
4. Upgrade or pin mkdocs-material if the icon set changed between versions.

Example fix

# before (page meta)
social:
  cards_icon: github

# after
social:
  cards_icon: fontawesome/brands/github

import pathlib, mkdocs
# check icon exists in any theme .icons dir before referencing it
icons_roots = [pathlib.Path(mkdocs.__file__).parent / 'themes' / 'material' / '.icons']
assert any((root / f"{icon_name}.svg").is_file() for root in icons_roots), f"icon {icon_name} not found"

from mkdocs.exceptions import PluginError
try:
    svg = plugin._resolve_icon(name)
except PluginError as e:
    log.warning(f"Icon missing, skipping: {e}")
    svg = None

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• Couldn't find layout '{name}'
• Couldn't find font family '{family}' on Google Fonts ({res.s
• Required dependencies of "social" plugin not found: {import_
• "cairosvg" Python module is installed, but it crashed with:
• Couldn't find image '{background.image}'

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