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.

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