One cause of an image not appearing in an EPUB is that the relative path written in the manuscript and the actual image location no longer agree. In the case tested here, export still succeeded. Use two checks: confirm the file exists from the manuscript's folder before export, then inspect the exported EPUB for missing resources.
This article covers why paths break, what happens when they do, and how to catch it before publishing. Choosing an image folder and writing the notation are covered separately.
A manuscript holds a route, not a location
What the manuscript contains is not the image but a route to it. images/plate1.png means "from the folder this manuscript is in, into images, then plate1.png".
Being a route, it breaks if either end moves.
- The image moved to another folder (destination changed)
- The manuscript moved to another folder (origin changed)
- The image was renamed (destination changed)
- A folder was renamed (the middle changed)
All four are things a writer does while "tidying up". Tidying is also, in practice, an operation that breaks routes.
Before export, resolve the path from the manuscript
Find each image reference in the manuscript and follow it from the folder containing that manuscript. If the destination file exists, that relative path is connected. If it does not, either move the image back or rewrite the manuscript path to the current location.
When you already know that an image moved, rune Studio can preview how many manuscript references would change from the old location to the new one. The tested preview returned one file and one occurrence, and the rewrite changed that path. This is not an automatic broken-path detector; it is a pre-export way to confirm and repair the scope of a known move.
Opening the result and checking
The obvious approach is opening the exported EPUB in a reading app and paging to each illustration.
The other is unpacking the file and looking at the images folder inside, comparing what should be there against what is.
The dangerous part is that the export succeeds
A broken image does not stop the export.
I verified this by driving the development build from the command line. After moving an image the manuscript pointed at into a different folder, the export completed and produced an EPUB. No error, no warning.
Open that file in a reading app and you find out only when you reach the chapter. If the illustration is in chapter nine, you find out in chapter nine.
Finding it after publication may require a replacement process. That is why the pre-export existence check and the post-export EPUB inspection are separate steps.
Unpacking is reliable but, with twenty illustrations, means reconciling twenty manuscript paths against twenty embedded files by hand. That is not a workable routine.
rune Studio names the broken reference
rune Studio can inspect an exported EPUB — reading order, navigation, missing images, leftover markup, empty pages — in one pass.
Inspecting the EPUB exported after moving the image, the verdict flipped to invalid, reporting that the body references an image not present in the EPUB, and naming which body file pointed at which image.
Running the same inspection on a healthy export reported two images present, zero missing, verdict valid. The same check tells you whether this missing-resource condition was found.
Inside an EPUB, image names change
One detail worth knowing: when an image is embedded, it does not keep the file name written in your manuscript. It is renamed based on the page it belongs to. The illustration that was plate1.png in the manuscript appeared inside the EPUB under a page-derived name.
So unpacking an EPUB and searching for your original file names will not find them. That is usually where a manual reconciliation falls apart.
Fixing it means rewriting the route
Once a break is found, the fix is in the manuscript's path. rune Studio can rewrite paths in bulk and reports the affected count first. Previewing the old and new locations returned one file and one occurrence; running it changed the path in the manuscript to the new location.
Who this suits, and who is fine without it
It suits anyone publishing a book with illustrations. Even a small number breaks once you reorganise a folder.
A book with no images does not need this step — for a text-only novel the same inspection is looking at other things.
Scope note: what was verified is whether the image is present inside the EPUB file. How a reading app renders it, and whether the size is appropriate, is outside this check.
Summary
- A manuscript path that no longer matches the image location is one cause of missing images
- The export succeeds anyway, so nothing warns you at the time
- Before export, resolve paths from the manuscript folder; for a known move, preview the affected references before rewriting
- rune Studio inspects the exported file and names which body file points at which missing image
- Image names change inside an EPUB, which is why manual reconciliation is confusing
For a first step, follow one image path from the manuscript folder and confirm that its file exists before export. A zero result after export means no missing-image finding within this inspection; rendering and store acceptance still need their own checks.
See the current product scope on the Rune Studio product page.
