EPUBCheck triage

How to fix EPUB validation errors

Do not repair a long report from top to bottom blindly. Fix the earliest broken layer first, rebuild the EPUB and let the validator remove downstream symptoms.

Published September 30, 20268 minute read

Repair order

Archive → container → package → content → CSS

Resolve fatal ZIP and container failures first. Then fix OPF manifest and spine references, malformed XML and missing resources. Treat CSS and recommendation warnings after the EPUB can be parsed completely.

Paste an EPUBCheck error →

EPUB validation repair order covering archive, manifest, spine, resources, XHTML and CSS. — One upstream path or parsing error may trigger several later messages. Revalidate after each structural layer.

1. Keep the complete diagnostic

Save the code, severity, file path, line and column. EPUBCheck uses stable message codes while other apps may shorten or rewrite the message.

2. Fix fatal archive errors first

PKG-003 and PKG-004 indicate unreadable EPUB or ZIP headers. PKG-006 means the mimetype entry is missing or not first. RSC-002 means META-INF/container.xml is missing. Until these are fixed, later content checks may never run.

3. Repair the OPF package graph

Resolve a missing OPF, invalid rootfile path, bad manifest href or spine idref. Common examples include OPF-002, OPF-003, OPF-049, RSC-007 and RSC-008. Match path case exactly.

4. Repair XML at the reported location

RSC-005 means an XML-based file could not be parsed. Check unclosed elements, incorrectly nested tags, unquoted attributes and bare ampersands. Save XHTML, OPF, nav and NCX resources as UTF-8.

5. Fix specialized content rules

For fixed layout, HTM-046 identifies a missing viewport and HTM-047 an invalid one. Image-header and media-type errors require opening or replacing the named asset, not changing unrelated XHTML.

6. Correct CSS and then review warnings

A CSS-008 parsing error usually points to invalid stylesheet syntax. After errors are cleared, evaluate warnings and usage messages. They may reveal compatibility or accessibility risk even when the EPUB technically passes.

7. Rebuild and validate the exact deliverable

Repackage the file correctly, run the current EPUBCheck release against that archive, and inspect the output in reading systems. A clean validator report does not guarantee good layout, navigation or readable text.

Turn a code into a repair step

The private lookup recognizes common package, resource, XML, viewport and CSS messages.

Open the error explainer →