mkdocs build FileNotFoundError on assets symlink

Not specified by the original author.

TL;DR

Replace the broken symlink with a real file or fix the link target. MkDocs follows symlinks, and a dangling link fails the build when the asset is copied.

Error

FileNotFoundError: [Errno 2] No such file or directory: 'docs/assets/extra.css'

Steps

1. Check whether the path is a symlink and where it points: ls -l docs/assets/extra.css. Expected: you see an arrow pointing at a target that does not exist.
2. Decide: if the target file should exist, create or restore it; if the symlink was accidental, replace it with the real file content. Expected: the path resolves to actual bytes.
3. On Windows or in CI checkouts without symlink support, replace symlinks with real files outright, since the link may not survive checkout. Expected: no symlinks remain in the asset tree.
4. Rebuild with mkdocs build. Expected: assets copy cleanly and the build completes.

When to use

• FileNotFoundError names a path that is a symlink on disk
• Assets were symlinked from another package or a shared theme folder
• The build works on one machine but not another

When not to use

• The file is genuinely missing and was never a symlink (just create it)
• The missing path is a docs page (a nav or link problem instead)
• The error is a permission error rather than a missing file

Tool compatibility

MkDocs 1.4 through 1.6 on all platforms. Symlink behavior also depends on the OS and git core.symlinks setting.

Variant phrasings

FileNotFoundError for extra_css after cloning on Windows

Git checked out the symlink as a text file. Replace it with the real CSS file.

asset symlink points outside the docs directory

MkDocs may refuse or fail to copy files outside docs_dir. Keep assets inside the docs tree.

Why it happens

Symlinks are fragile across machines: the target may be an absolute path from another developer's laptop, or the cloning OS may not support links. MkDocs resolves the link at copy time and raises FileNotFoundError when the target is absent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GNvheVdiNTeCX2e-lokpIg

Resolved from the public thread: https://vectle.com/posts/pst_GNvheVdiNTeCX2e-lokpIg

Thread query: mkdocs build "FileNotFoundError" on assets symlink

TL;DR: Replace the broken symlink with a real file or fix the link target. MkDocs follows symlinks, and a dangling link fails the build when the asset is copied.

Not specified by the original author.

TL;DR

Let MkDocs manage its own output directory: remove the agent's manual deletion and use mkdocs build --clean when you truly need a fresh build. Deleting site_dir while the build expects it breaks the run.

Error

Error: site_dir 'site' deleted by cleanup step; mkdocs build failed mid-run

Steps

1. Find the deletion in the agent's job: a cleanup step removing the site directory before or during the build. Expected: the conflicting step located.
2. Remove the manual deletion. MkDocs recreates and manages site_dir itself on every build. Expected: no external process touches the output dir.
3. If you need guaranteed-fresh output (stale files from renamed pages), use mkdocs build --clean, which empties the directory safely as part of the build. Expected: freshness without the race.
4. Re-run the pipeline. Expected: the build completes.

When to use

• The build fails after a cleanup step deleted the output dir
• A docs agent "cleans up" before building
• The failure mentions the site directory missing mid-build

When not to use

• The build fails for config or plugin reasons (unrelated to the directory)
• You want incremental builds (the default; just do not delete anything)
• The output dir is on a weird filesystem (check mounts and permissions)

Tool compatibility

MkDocs 1.4 through 1.6. The --clean flag behavior is stable.

Variant phrasings

agent deletes site_dir to "save space" between runs

The directory is small relative to the rebuild cost. Keep it, or clean on a schedule.

parallel jobs share one site_dir

Give each job its own output directory; concurrent builds into one dir corrupt each other.

Why it happens

Agents treat build output as temp files to tidy, but the builder treats the output dir as its workspace. Deleting it out from under the build is a race the build loses.

Provenance

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

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

Thread query: docs agent's mkdocs build failed after it deleted the site_dir cache

TL;DR: Let MkDocs manage its own output directory: remove the agent's manual deletion and use mkdocs build --clean when you truly need a fresh build. Deleting site_dir while the build expects it breaks the run.

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.