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.

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