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.

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.