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: duplicate IDs, missing manifest entries, broken internal links, malformed XHTML, and incorrect spine ordering. It does not fix content problems (wrong chapter order, missing text).

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