OddproofSign inYour accountAccount
Oddproof
Your account Sign in
Guides / EPUB

EPUBCheck navigation error: repair the package, preserve the chapters

An EPUBCheck error does not necessarily mean you need to rewrite or reconvert a book. Sometimes the chapter files are intact and a package declaration is missing. This example shows one such case, and how we checked what changed.

10 Sep 2026 · original demonstration · prepared by Oddproof with AI and software checks

The navigation document existed. Its declaration was incomplete.

Our original, two-chapter demonstration book already had a nav.xhtml contents document with working chapter links. The package manifest listed it without the navigation property. The repair changes this item in EPUB/package.opf:

Before:

<item id="nav" href="nav.xhtml"
  media-type="application/xhtml+xml"/>

After:

<item id="nav" href="nav.xhtml"
  media-type="application/xhtml+xml"
  properties="nav"/>

This is appropriate because that file is already the EPUB navigation document. Adding the property to an arbitrary file, or to a document with broken links, would not resolve the underlying problem.

What the checks established

In the saved sample run, EPUBCheck 5.3.0 reported one error and zero warnings for the original. The corrected book returned zero errors and zero warnings. The sample pack includes both full reports.

  • Both chapter files remained byte-for-byte identical.
  • The contents document, CSS, reading order and publication metadata were preserved.
  • Six of seven archive entries stayed identical. Only the package document changed.
  • Separate checks covered ZIP integrity, XML syntax and the two chapter links and fragments.

A useful repair sequence

  1. Keep the original EPUB and the complete validator report.
  2. Find the exact error and the file it names. Check whether the problem concerns the package, navigation, markup or media.
  3. Make the smallest justified change in a separate copy. Preserve the intended reading order.
  4. Rerun a whole-file validation and compare the archive entries, text and media.
  5. Check the result on the intended reading platform too.

A validator pass supports a specific structural result. It does not establish device rendering, accessibility conformance or retailer acceptance. This fictional sample is not evidence that every EPUB error has the same fix.

Inspect the files and the specification

Download the original EPUB, repaired copy and check reports.

Technical references: W3C EPUB manifest properties and EPUBCheck 5.3.0.

Rather have it done? EPUB structural repair →