When an EPUB image does not display, trace the chain in order: source file, manuscript path, packaged resource, and XHTML reference. Do not delete the source while diagnosing it.
When working on EPUB image not displaying, consider a chapter-folder cleanup after which only the diagram in chapter two becomes blank. The task is complete only when source asset existence and agreement between XHTML src and packaged filename can both be confirmed after the saved output is reopened. An export message by itself does not answer the search question.
Decide what success means for this book
For this example—a chapter-folder cleanup after which only the diagram in chapter two becomes blank—the first decision is whether source asset existence has a known starting value. The final decision is whether agreement between XHTML src and packaged filename survives export and reopening. Keeping those two moments separate prevents a temporary editor display from becoming the handoff criterion.
Preserve the received manuscript, edit a working duplicate, and write the EPUB separately. With EPUB image not displaying as the goal, those three files keep the source, intentional edits, and packaged book distinct.
The direction is one-way: preserved source, editable duplicate, separately written EPUB, then a reopened EPUB. The method does not recreate the manuscript from the EPUB or treat the package as an editing source.
Build a representative test case
Build the example around a chapter-folder cleanup after which only the diagram in chapter two becomes blank. Keep the part that could genuinely fail. If the risk concerns filename case, include the exact chapter, character, path, or label that creates that risk. Removing it for a cleaner demo would produce an easy pass with no value for the real book.
Examine four independent facts
- Source asset existence: while you record the failing page and asset name, write down the expected state and what the book actually shows. Treat this as its own decision; do not infer it from filename case.
- Filename case: while you open the untouched source image, write down the expected state and what the book actually shows. Treat this as its own decision; do not infer it from manifest inclusion.
- Manifest inclusion: while you resolve the manuscript relative path, write down the expected state and what the book actually shows. Treat this as its own decision; do not infer it from agreement between XHTML src and packaged filename.
- Agreement between XHTML src and packaged filename: while you examine manifest and packaged image directory, write down the expected state and what the book actually shows. Treat this as its own decision; do not infer it from source asset existence.
Complete the operation in order
- Record the failing page and asset name. Before moving on, confirm source asset existence; if it differs from the expected state, correct that step rather than compensating later.
- Open the untouched source image. Before moving on, confirm filename case; if it differs from the expected state, correct that step rather than compensating later.
- Resolve the manuscript relative path. Before moving on, confirm manifest inclusion; if it differs from the expected state, correct that step rather than compensating later.
- Examine manifest and packaged image directory. Before moving on, confirm agreement between XHTML src and packaged filename; if it differs from the expected state, correct that step rather than compensating later.
- Export a new EPUB and reopen the same page. Before moving on, confirm source asset existence; if it differs from the expected state, correct that step rather than compensating later.
Walk the example from source to handoff
During step 1, record the failing page and asset name. In the case of a chapter-folder cleanup after which only the diagram in chapter two becomes blank, examine source asset existence before changing anything else. This prevents deleting an apparently unused image first. If the observation is unknown, repeat that step with the working duplicate instead of editing the master manuscript.
During step 2, open the untouched source image. In the case of a chapter-folder cleanup after which only the diagram in chapter two becomes blank, examine filename case before changing anything else. This prevents ignoring filename case because macOS opens it. If the observation is unknown, repeat that step with the working duplicate instead of editing the master manuscript.
During step 3, resolve the manuscript relative path. In the case of a chapter-folder cleanup after which only the diagram in chapter two becomes blank, examine manifest inclusion before changing anything else. This prevents mistaking visible alt text for a packaged image. If the observation is unknown, repeat that step with the working duplicate instead of editing the master manuscript.
During step 4, examine manifest and packaged image directory. In the case of a chapter-folder cleanup after which only the diagram in chapter two becomes blank, examine agreement between XHTML src and packaged filename before changing anything else. This prevents deleting an apparently unused image first. If the observation is unknown, repeat that step with the working duplicate instead of editing the master manuscript.
During step 5, export a new EPUB and reopen the same page. In the case of a chapter-folder cleanup after which only the diagram in chapter two becomes blank, examine source asset existence before changing anything else. This prevents ignoring filename case because macOS opens it. If the observation is unknown, repeat that step with the working duplicate instead of editing the master manuscript.
What the example showed
The trial produced this observation: The test book exported 2 chapters with writingMode=horizontal and version 1.6. Inspection returned spine=6, images=1, missing=0, nav=true, NCX=true, and valid=true.
That value belongs to the files and settings used for this example. It supports the documented sequence; it does not turn EPUB image not displaying into a promise for every manuscript, reading system, or retailer.
The untested boundary is equally important: valid=true is a local package outcome, not retailer acceptance or identical rendering in every reader. Outside this scope: Copyright clearance, identical rendering in every reader, and retailer acceptance are outside scope. Add retailer preview, device testing, accessibility review, or rights clearance when the book requires those decisions.
The W3C EPUB 3.3 specification defines the EPUB navigation document as a required publication component.
Recover from the three likely mistakes
- Deleting an apparently unused image first: go back to “record the failing page and asset name,” then re-examine source asset existence. Change only the responsible input so the next comparison remains meaningful.
- Ignoring filename case because macOS opens it: go back to “open the untouched source image,” then re-examine filename case. Change only the responsible input so the next comparison remains meaningful.
- Mistaking visible alt text for a packaged image: go back to “resolve the manuscript relative path,” then re-examine manifest inclusion. Change only the responsible input so the next comparison remains meaningful.
Decide whether Rune Studio fits
Rune Studio is a candidate when an editor wants manuscript work and EPUB preparation in one Mac application for a project involving a chapter-folder cleanup after which only the diagram in chapter two becomes blank. Product documentation describes available functions; the observation above documents only this example.
See the product on the Rune Studio website. Keep the adoption boundary explicit: copyright clearance, identical rendering in every reader, and retailer acceptance are outside scope.
Take the next step
Start with this action: record the failing page and asset name. Then follow the remaining steps until agreement between XHTML src and packaged filename can be reproduced from the reopened publication. That is the practical finish line when working on EPUB image not displaying.