sphinx WARNING: image file not readable build failed

Not specified by the original author.

TL;DR

Fix the image path so it resolves relative to the source file that references it, and confirm the file actually exists with read permission. Image paths in Sphinx are relative to the document, not to the project root.

Error

WARNING: image file not readable: images/architecture.png

Steps

1. Note which source file produced the warning (Sphinx prints the document name above the warning) and list the image directory relative to that file. Expected: you can see whether the file exists at the referenced location.
2. Correct the path in the .. image:: or .. figure:: directive so it is relative to the referencing document, e.g. ../images/architecture.png if the images live one level up. Expected: the path matches the real file location.
3. Check the file is a format Sphinx accepts (png, jpg, svg, pdf for LaTeX) and is readable: file images/architecture.png. Expected: the file command reports an image type, not empty or corrupt data.
4. Rebuild and confirm the warning is gone and the image renders in the HTML output. Expected: zero image warnings and a visible image on the page.

When to use

• Build log shows "image file not readable" under an image or figure directive
• Images render locally but break after the docs folder was reorganized
• A docs agent generated image references with wrong relative paths

When not to use

• The image exists but is the wrong size or format (an asset problem, not a path problem)
• The warning names a download file (that is the download role, different fix)
• Images are remote URLs, which Sphinx does not fetch at build time

Tool compatibility

Sphinx 5.x through 8.x, all builders. MyST Markdown uses the same relative-path rule for its image syntax.

Variant phrasings

figure directive reports the image as not readable

Identical cause and fix; the figure directive wraps the same image lookup.

image works in HTML but warns in the LaTeX build

The LaTeX builder needs the image in a format it can embed. Convert to PDF or PNG, or mark the image for HTML only.

Why it happens

Authors usually write the path as they see it from the project root, but Sphinx resolves it from the document's own directory. Moving either the document or the image folder breaks the reference silently until the build warns. Case-sensitive filesystems also break references written with the wrong capitalisation.

Provenance

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

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

Thread query: sphinx "WARNING: image file not readable" build failed

TL;DR: Fix the image path so it resolves relative to the source file that references it, and confirm the file actually exists with read permission. Image paths in Sphinx are relative to the document, not to the project root.

Not specified by the original author.

TL;DR

Delete or correct the stale toctree entry, or create the missing document file, then rebuild. Each toctree entry must match an existing source file name exactly, without the file extension. The warning names the offending entry so you can find it in seconds.

Error

WARNING: toctree contains reference to nonexisting document 'api/client'

Steps

1. Copy the document name from the warning and search your source tree for a file with that name plus a source suffix: find docs -name "client*". Expected: you see which expected file is absent.
2. Open the file containing the toctree directive (often index.rst) and locate the entry that matches the warning text. Expected: the entry is visible under a .. toctree:: block.
3. If the document was renamed, update the entry to the new name. If it was deleted on purpose, remove the entry line. If it should exist, create the file. Expected: every toctree entry now matches a real file.
4. Rebuild with sphinx-build -b html docs docs/_build and confirm the warning is gone from the output. Expected: zero toctree warnings in the build log.

When to use

• Sphinx build log contains "toctree contains reference to nonexisting document"
• A docs page was renamed or deleted and the index was not updated
• A new toctree entry was added before its file was created

When not to use

• The warning is about a missing image or download file, not a document
• The document exists but fails to import under autodoc (different failure)
• You want glob-style toctrees, which need explicit :glob: option handling instead

Tool compatibility

Sphinx 5.x through 8.x, any builder. Also applies to MyST Markdown toctrees, where the same rule covers .md source files.

Variant phrasings

toctree references a document that was moved

WARNING: toctree contains reference to nonexisting document 'guide/setup'

Same fix: update the entry to the new path after the move.

toctree warning after a branch merge

The entry is correct on one branch but the file only exists on another. Check out the right branch or merge the missing file before rebuilding.

Why it happens

Sphinx resolves each toctree entry to a source document at build time. When a file is renamed, moved, or deleted without updating the toctree, the reference dangles and Sphinx warns instead of guessing. Case sensitivity matters on Linux builds: API/client and api/client are different documents.

Provenance

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

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

Thread query: sphinx "WARNING: toctree contains reference to nonexisting document" build failed

TL;DR: Delete or correct the stale toctree entry, or create the missing document file, then rebuild. Each toctree entry must match an existing source file name exactly, without the file extension. The warning names the offending entry so you can find it in seconds.

Not specified by the original author.

TL;DR

Rewrite the image paths to match the new relative locations, or move the images with the docs so relative paths still hold. Relative paths encode the old layout.

Error

WARNING: image file not readable: ../assets/diagram.png (after moving docs/ to website/docs/)

Steps

1. Map the old layout to the new one: for each referencing document, compute the new relative path to its image. Expected: the path delta understood.
2. Rewrite the references. A scripted find-and-replace over the moved tree beats hand edits; verify with the build warnings. Expected: references match the new layout.
3. Alternative: move the image assets along with the docs so the relative relationships are unchanged. Expected: zero reference changes needed.
4. Rebuild and confirm zero image warnings and rendered images. Expected: images resolve.

When to use

• Images broke after moving the docs folder
• A docs agent reorganized the tree
• The site moved from docs/ to a nested path

When not to use

• Images were already broken before the move (a pre-existing path problem)
• Images use absolute or URL paths (unaffected by moves)
• The move also renamed images (fix names and paths together)

Tool compatibility

Sphinx, MkDocs, Docusaurus. Relative-path semantics are the same everywhere.

Variant phrasings

agent moved docs but left images behind

Move the assets too, or rewrite every reference; there is no third option.

paths fixed but images still missing in CI

The images are gitignored or in LFS without pull. Check version control, not paths.

Why it happens

Relative paths are only correct for one layout. Any reorganization invalidates them, and the breakage is silent until the next build warns.

Provenance

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

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

Thread query: docs agent failed: could not resolve relative image paths after docs folder move

TL;DR: Rewrite the image paths to match the new relative locations, or move the images with the docs so relative paths still hold. Relative paths encode the old layout.