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 handles three things: incorrect or missing mimetype content, a missing META-INF/container.xml, and a missing dc:language. Duplicate IDs, missing manifest entries, broken links, malformed XHTML, and spine ordering are detected but need manual repair.

The 10 Most Common Errors

1. Duplicate IDs

ERROR: Duplicate ID "chapter-1"

Every id attribute must be unique across the entire EPUB. This happens when chapters from different sources reuse the same IDs. Fix: rename duplicates. The merge tool handles this automatically during merging.

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

EPUB 3 core media types: JPEG, PNG, GIF, SVG. WebP, AVIF, and BMP are not in the spec and will fail validation. Fix: convert to JPEG or PNG.

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

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