How to Repair Common EPUB Errors

Start by finding out what is wrong

Run the book through the EPUB Validator before you change anything. The codes it prints tell you which of the problems below you have. Fixing without a diagnosis tends to make things worse, especially if you re-zip the book by hand, which can break the very rule that makes an EPUB an EPUB.

Error 1: the archive layout is wrong

Symptom: strict readers refuse the file; the validator reports that mimetype is not first, is compressed, or has extra data.

Cause: the book was unzipped, edited and zipped again with a normal archive program. EPUB requires the first entry to be a stored (uncompressed) file named mimetype holding exactly application/epub+zip.

Fix: rebuild the archive in that order. The repair tool does this whenever it writes a file.

Error 2: the container points at nothing

Symptom: the book does not open at all; the validator reports that container.xml is missing or names a package file that does not exist.

Fix: create META-INF/container.xml with a rootfile entry whose full-path is the real path of the .opf. The repair tool does this when the archive contains a single package file. If there are several, it will not guess.

Error 3: the manifest lists files that are not there

Symptom: a chapter is missing, or the book opens but stops early.

Fix: remove the manifest item and its itemref in the spine, and any contents entries that pointed to it, or restore the missing file. If the file exists under another name, correct the href. The repair tool removes entries for files that do not exist and, where the table of contents still points to a document that is present but not in the reading order, puts it back in order.

Error 4: required metadata is empty

Symptom: the validator reports a missing title, language or identifier.

Fix: set real values. The repair tool fills in neutral placeholders (Untitled, und, a generated identifier) so the file becomes valid, and tells you. Replace them afterwards with the metadata editor.

Error 5: undeclared entities

Symptom: the book fails to display a chapter, or a strict reader shows a parsing error; the validator reports HTM-003.

Cause: XHTML is XML, and XML knows only five named entities (& < > " '). HTML names such as   and — are not declared in an EPUB’s XHTML.

Fix: replace them with numeric references ( , —) or the characters themselves. The repair tool does this for the common names.

Error 6: navigation out of date

Symptom: the table of contents is missing or links to nowhere.

Fix: EPUB 3 needs a navigation document marked with the nav property; EPUB 2 needs an NCX file named in the spine. The repair tool generates one from the reading order if it is absent, and removes entries that point to files which do not exist.

What cannot be repaired by rules

• A truncated or corrupt ZIP. Obtain the file again.
• Chapters that are not well-formed XML in the middle of the text. They need editing in a tool that understands the content.
• DRM-protected books.
• Conversions that mangled the text itself, such as wrong character encoding.

Running the repair

1. Open EPUB Repair and choose the book.
2. Press Repair EPUB.
3. Read the list of changes and the errors that remain.
4. Download the repaired copy, open it in your reader and compare it with the original before discarding anything.

The original file is never changed; the repair produces a separate file with -repaired in its name.

A worked example

A test book was broken on purpose in three ways: its archive was written with mimetype not first, the manifest named text/gone.xhtml which does not exist, and the language field was removed. The validator reported four errors. After repair the report was:

• Removed manifest entry ch2 because text/gone.xhtml is not in the archive.
• Removed the spine reference to the missing item.
• Added dc:language “und” because it was missing.
• Added OEBPS/text/ch2.xhtml to the manifest, because the file existed under its original name.
• Added that chapter back to the reading order because the table of contents linked to it, in the position the table of contents gives it.
• Rewrote the archive so mimetype is first and uncompressed.

The result had no errors, and W3C EPUBCheck reported no errors or warnings either. That example also shows what a repair is: it does not guess content, it makes the existing pieces consistent.

Doing it by hand

If you prefer a text editor, the steps are the same as the tool’s. Unzip the book to a folder. Open META-INF/container.xml and the .opf file. For each manifest item, check that the file exists at that path. For each spine entry, check that its id is in the manifest. Fix or remove what does not match. To rebuild, create the ZIP so that mimetype is added first with no compression. With the standard zip command that is:

zip -X0 book.epub mimetype
zip -Xr9D book.epub META-INF OEBPS

The -0 stores the first file without compression and -X leaves out extra attributes. Graphical archive programs rarely let you control the order, which is why hand-zipped books so often fail.

How to tell a repair worked

1. The validator reports no errors on the repaired file.
2. The chapter count in the reader matches the original table of contents.
3. The book opens in the reading app that rejected it before.