squidfunk/mkdocs-material · error · PluginError

Couldn't find project '{slug}'

Error message

Couldn't find project '{slug}'

What it means

After parsing a project:// URL, the plugin matches the slug against the known projects collected during the build. If no project's reference matches the requested slug, target remains None and the plugin raises PluginError stating the project could not be found. This means the referenced name does not correspond to any project registered in the projects plugin configuration.

Source

Thrown at src/plugins/projects/plugin.py:289

        # Compute slug from host name and convert to dot notation
        slug = url.hostname
        slug = slug if slug.startswith(".") else f".{slug}"

        # Resolve source and target project
        source: Project | None = None
        target: Project | None = None
        for ref, file in self.manifest.items():
            base = os.path.join(self.config.projects_root_dir, file)
            if file == os.path.relpath(
                config.config_file_path, self.config.projects_root_dir
            ):
                source = Project(base, self.config, ref)
            if slug == ref:
                target = Project(base, self.config, ref)

        # Abort if slug doesn't match a known project
        if not target:
            raise PluginError(f"Couldn't find project '{slug}'")

        # Return project slug and path
        return target, target.path(source)

View on GitHub (pinned to e2136532f4)

Solutions

1. Check the exact slug in the link against the projects declared in the projects plugin config and fix the spelling
2. Add the missing project to the projects plugin configuration if it should be part of the build
3. Use the project directory/reference name (as listed in config) rather than an arbitrary hostname

Example fix

// before
[API docs](project://api-doc
// after
[API docs](project://api-docs)

import os, yaml
cfg = yaml.safe_load(open("mkdocs.yml"))
projects = [p for p in (cfg.get("plugins", {}).get("projects", {}) or {}).get("projects", [])]
slug = "api-docs"
assert slug in projects or os.path.isdir(slug), f"Unknown project '{slug}'"

try:
    mkdocs build
except SystemExit:
    # cross-check the slug in the message against projects config
    pass

When it happens

Trigger: _replace resolves a project://slug link where slug matches neither a project directory name/reference nor the slug derived from project hosts configured in the projects plugin config.

Common situations: Typo in the project name inside a project:// link; referencing a project that is not listed under the projects plugin's config; renaming a project directory without updating cross-project links; links copied from another docs site.

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

• Aborted with {len(errors)} configuration errors
• Couldn't resolve project URL: paths currently not supported
• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Unknown shortcode: {type}

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