mkdocs build "FileNotFoundError" on assets symlink
Fixes MkDocs builds that fail with FileNotFoundError when an asset path is a broken symlink. Use when the traceback points at a symlinked asset like extra_css. Not for missing config keys or YAML errors.
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
- 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. - 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.
- 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.
- 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