How to Fix EPUB Errors

EPUB validation errors mean a reader app or store might reject your file, render it incorrectly, or silently drop content. The Epublys validator catches these and can auto-fix the common ones. Here's what the errors mean and how to fix them manually when you need to.

Auto-Fix: Epublys Validator

1. Open the EPUB validator
2. Upload your file and enable Deep scan
3. Turn on Auto-fix issues
4. Download the repaired file

Auto-fix repairs missing or incorrect mimetype content, its position as the first ZIP entry, and a missing dc:language. A missing language is filled with en; check that it matches the book. A correct, first-entry mimetype that is only ZIP-compressed is not repaired by auto-fix alone: repack it as STORE. Auto-fix does not recreate container.xml, missing chapters or arbitrary links. The scan reports duplicate manifest IDs, missing manifest files, invalid spine references and, with Deep scan, malformed XHTML and references to missing files. EPUBCheck is needed for checks outside that subset.

The 10 Most Common Errors

1. Duplicate IDs

ERROR: Duplicate ID "chapter-1"

IDs must be unique within the XML document that contains them. Two chapter documents can each have an anchor named chapter-1; duplicate IDs within one chapter or within the OPF are errors. The merge tool gives manifest IDs book-specific prefixes. For duplicate chapter anchors, use an EPUB editor and update the links that point to them.

2. Missing manifest entry

ERROR: File "images/photo.jpg" not in manifest

Every file in the ZIP must be declared in the OPF <manifest>. Fix: add the <item> element, or delete the unreferenced file.

3. Broken internal links

ERROR: Hyperlink target "chapter3.xhtml" not found

A link in the content points to a file that doesn't exist. Usually a typo or a file that was renamed without updating references. Fix: correct the href attribute.

4. Invalid XHTML

ERROR: Element "br" not terminated

EPUB requires well-formed XHTML, not HTML. Common issues: unclosed tags (<br> should be <br/>), unescaped ampersands (& instead of &), attribute values without quotes.

5. Missing or incorrect mimetype

ERROR: Mimetype file missing or incorrect

The first file in the ZIP must be mimetype containing exactly application/epub+zip with no newline, stored uncompressed. Fix: repack the ZIP correctly. The compressor handles this automatically.

6. Spine item not in manifest

ERROR: Spine itemref "ch5" references missing manifest item

The reading order (<spine>) references an ID that doesn't exist in the <manifest>. Fix: add the missing manifest item or remove the spine reference.

7. CSS errors

WARNING: CSS property "text-rendering" not recognized

Most CSS warnings are non-fatal. Readers ignore unknown properties. Only fix these if a store (like Apple Books) rejects the file.

8. Missing nav document (EPUB 3)

ERROR: No navigation document found

EPUB 3 requires a nav.xhtml file with properties="nav" in the manifest. EPUB 2 uses an NCX file instead. Fix: add the nav document or convert to EPUB 2.

9. Image format not supported

ERROR: Image type "image/webp" not allowed

Image support depends on the EPUB version and reader. The current EPUB 3.3 specification includes WebP as a core image type; older readers may still need JPEG or PNG. Check the actual validation message and destination compatibility instead of assuming every image-format warning requires conversion.

10. File path issues

ERROR: File path contains spaces or special characters

Some readers choke on spaces, accented characters, or colons in file paths inside the EPUB. Fix: rename files to use only ASCII alphanumeric characters, hyphens, and underscores.

Other tools

EPUBCheck (W3C): The reference validator. Command-line only: java -jar epubcheck.jar book.epub. Reports errors but does not fix them.

Sigil: Open the EPUB, run Tools → Check for Errors. Sigil lets you fix issues directly in the XHTML editor. Best for manual, surgical fixes.

Calibre: Convert EPUB to EPUB with "Clean up the EPUB" checked. Fixes some structural issues but can also introduce new ones by restructuring the HTML.

Related

• What is an EPUB file? — internal structure explained
• How to create an EPUB — start right and avoid errors
• All free EPUB tools