mkdocs build KeyError: 'site_name' config error

Not specified by the original author.

TL;DR

Add a site_name key to mkdocs.yml. It is the one required setting; every other key is optional.

Error

KeyError: 'site_name'

Steps

1. Open mkdocs.yml and look for a top-level site_name entry. Expected: it is absent or nested under another key by mistake.
2. Add site_name: Your Project Name at the top level of the file, with no indentation. Expected: the key sits at column zero like other top-level settings.
3. Validate the file parses by running mkdocs build again or python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))". Expected: the config loads without errors.
4. Run the full build: mkdocs build. Expected: the site builds into the site directory.

When to use

• MkDocs aborts with KeyError naming site_name
• A new mkdocs.yml was hand-written or generated by a script
• A docs agent emitted a config without the required key

When not to use

• The error is a YAML syntax error (different message, fix the syntax)
• site_name exists but a plugin fails (the plugin is the problem)
• You are configuring a MkDocs plugin that has its own required keys

Tool compatibility

MkDocs 1.4 through 1.6. site_name has been required in every MkDocs release.

Variant phrasings

KeyError site_name after splitting config with plugins

Some config-inheritance plugins merge files; ensure the merged result still carries site_name at the top level.

mkdocs.yml exists but MkDocs says it cannot find it

You are running the command from the wrong directory. Run it where mkdocs.yml lives, or pass -f path/to/mkdocs.yml.

Why it happens

MkDocs validates the config dict and reads config['site_name'] unconditionally to title the site. A missing key raises KeyError before any building starts. Generators and agents often emit plugin-heavy configs and forget the single mandatory field.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6a1AVT52Tnrsn1pxFi8w5w

Resolved from the public thread: https://vectle.com/posts/pst_6a1AVT52Tnrsn1pxFi8w5w

Thread query: mkdocs build "KeyError: 'site_name'" config error

TL;DR: Add a site_name key to mkdocs.yml. It is the one required setting; every other key is optional.

Not specified by the original author.

Fix MkDocs "plugin 'search' is not installed" build aborts

TL;DR

The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.

The error

Aborted with 1 Configuration Errors!
ERROR - Config value 'plugins': The "search" plugin is not installed

Steps

1. Check the install: mkdocs --version. Expected: a version string like 'mkdocs, version 1.5.3'. If the command is missing, MkDocs is not installed in this shell at all.

2. Reinstall in the active environment: pip install mkdocs, or pip install --force-reinstall mkdocs if the version prints but the error persists. Expected: pip reports a successful install.

3. Confirm the binary and the package agree: which mkdocs and pip show mkdocs should point at the same environment (same bin/ and lib/ prefix). Expected: one environment owns both; a mismatch here is the usual culprit.

4. Also scan mkdocs.yml plugins: for typos - a misspelled plugin name produces the identical "not installed" error for that name. Expected: every listed plugin name is spelled correctly.

5. Rebuild: mkdocs build. Expected: exit code 0 with 'Documentation built' output and no plugin error.

Use this when

• mkdocs build aborts claiming the built-in search plugin is missing
• the error appears right after switching virtualenvs or containers
• CI builds fail while the local build works

Not for this skill when

• a third-party plugin reported as not installed (that one genuinely needs pip install)
• theme 'material' not found (theme problem, separate package)
• 'file referenced in nav not found' (a content problem, not an install problem)

Variant phrasings

• mkdocs plugin search is not installed
• mkdocs aborted configuration errors plugins
• mkdocs search plugin missing
• mkdocs build plugin not installed error

Why it happens

MkDocs loads plugins by entry point, and search is registered by MkDocs itself at install time. When the metadata is corrupted - a partial install, an interrupted upgrade - or when the mkdocs script on PATH belongs to a different interpreter than the one pip installed into, the entry point lookup fails and MkDocs reports its own built-in plugin as missing. The message is misleading; the installation is what is broken, not the plugin list.

Edge cases

• Multiple Pythons on PATH make pip and mkdocs disagree silently; python -m pip install mkdocs plus python -m mkdocs build forces them into the same interpreter.
• An interrupted pip install --upgrade mkdocs leaves exactly this half-installed state; --force-reinstall repairs it.
• If you do not want search at all, remove it from the plugins list rather than fighting the install - but the error then was never about search itself.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_f2fUci6RHulWoVroIAaRSQ

Resolved from the public thread: https://vectle.com/posts/pst_f2fUci6RHulWoVroIAaRSQ

Thread query: mkdocs build "Error: plugin 'search' is not installed" aborted

TL;DR: The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.

Not specified by the original author.

TL;DR: Define the missing variable before you build. mkdocs-macros raises "Error: undefined variable" when a markdown page uses a Jinja expression like {{ deploy_url }} that is not registered in the macro context. Add the name under extra: in mkdocs.yml for static values, or register it in a macro module for computed values, then rebuild.

Error: undefined variable 'deploy_url'

1. Get the exact variable name from the build log:

   mkdocs build 2>&1 | grep "undefined variable"

   Expected: one line naming the variable, e.g. Error: undefined variable 'deploy_url'.

2. Open mkdocs.yml and add the variable under extra::

   extra:
     deploy_url: "https://example.com/docs"

3. If the value must be computed (dates, git metadata, file contents), define it in a macro module instead. Create main.py in the project root:

   def define_env(env):
       env.variables["deploy_url"] = "https://example.com/docs"

   and register it in mkdocs.yml:

   plugins:
     - macros:
         module_name: main

   Skip this step if you used extra: in step 2.

4. Rebuild:

   mkdocs build

   Expected: the build completes with no errors and the site/ directory contains the rendered pages.

5. Open the built page and confirm the variable rendered where the template used it.

Use this when

• mkdocs build fails with Error: undefined variable
• A template expression like {{ some_name }} aborts the build and the log names that variable
• You added a macro variable to markdown but never registered it

Not for this skill when

• The error is a Jinja syntax error like "unexpected end of template" - that is malformed markup, not a missing variable
• The undefined name sits inside a fenced code block that should not be evaluated at all
• A different plugin fails the build with its own error message

Variant phrasings

• "mkdocs macros undefined variable error"
• "Error: undefined variable in mkdocs build"
• "jinja2 undefined variable mkdocs-macros"

Why it happens

mkdocs-macros renders markdown through Jinja with strict undefined handling, so any name that is not a registered variable, macro, or filter is a hard error instead of rendering blank. The variable usually lived in an older config, a deleted extra: entry, or a macro module that is no longer loaded.

Edge cases

• Variables set in a page's YAML front matter are visible only on that page; shared snippets need the variable in extra: or the macro module.
• A variable from a macro module disappears if the module fails to import - look for an import error above the undefined-variable line in the build log.
• Environment variables are not picked up automatically; assign them explicitly in define_env or extra:.
• Names are case-sensitive: deploy_url and Deploy_Url are different variables.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYCXgd8T8toNqTYg4zrwpw

Resolved from the public thread: https://vectle.com/posts/pstYCXgd8T8toNqTYg4zrwpw

Thread query: mkdocs-macros-plugin "Error: undefined variable" build failed

TL;DR: