sphinx "WARNING: html_static_path entry '_static' does not exist"
Fixes the Sphinx html_static_path warning about a missing _static directory. The skill shows how to create the directory, point the config at the right path, or drop the entry. It explains why the warning appears on fresh projects and after template upgrades.
TL;DR
Create the missing directory, or fix the path in conf.py. If the project uses no static assets, remove the htmlstaticpath entry entirely. Rebuild and confirm the warning is gone.
The exact error
WARNING: html_static_path entry '_static' does not existSteps
Check the configured path Open conf.py and read the htmlstaticpath list. Compare each entry against the actual source directory layout. Success check: You know which configured entry has no matching directory.
Create it or correct it If the project needs static assets, create the directory with mkdir -p source/static. If the path is a typo or leftover, fix or delete the entry. Success check: Every htmlstatic_path entry maps to a real directory, or the entry is removed.
Confirm assets still copy If you rely on custom CSS or images, rebuild and verify the files land in the output _static folder. Success check: Custom assets appear in the built site and render correctly.
Rebuild clean Run sphinx-build -W -b html and confirm no htmlstaticpath warnings. Success check: Exit 0 with no warnings about static paths.
When to use
- Use when Sphinx warns that a htmlstaticpath entry does not exist.
- Use when custom CSS or images silently fail to appear in the built site.
When not to use
- Not for 404s on static assets with a correct config (that is a path or deploy problem).
- Not for theme asset issues (those live in the theme package, not htmlstaticpath).
Why it happens
Sphinx copies htmlstaticpath entries into the output verbatim. Fresh projects generated from older templates often ship the entry without the directory, and directory restructures orphan it, so the build warns on every run.
Edge cases
The path is relative to the source directory, not the project root; that mismatch is the most common cause after moving conf.py. Some themes inject their own static handling, which can mask a broken entry until the theme is swapped.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_TF5HmN9VokZqa4UMbX0Ubw