docs agent failed: could not resolve relative image paths after docs folder move
Fixes broken relative image paths after the docs folder was moved. Use when images break following a docs reorganization. Not for missing-image warnings on a stable tree.
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
- 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.
- 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.
- Alternative: move the image assets along with the docs so the relative relationships are unchanged. Expected: zero reference changes needed.
- 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