epubcheck is the canonical conformance checker for EPUB, maintained by the DAISY Consortium and the W3C community. It reads your file against the EPUB specification and reports every deviation as an ERROR or a WARNING, each tagged with a short code such as RSC-005. The codes look cryptic, but almost all of them are mechanical: a missing file, an attribute in the wrong place, or a resource that should not be there.
This guide walks the error families you will actually hit, what causes each one, and the typical fix. The golden rule: clear every ERROR line first — errors break conformance and can stop reading systems from opening the book — then work through the WARNING lines. Origami runs the same epubcheck engine, explains every finding in plain language, and sorts the blockers to the top so you know exactly what to touch first.
Schema errors: RSC-005
RSC-005 is the workhorse error, and the one that alarms people most. It means a file failed schema validation against the spec — the XML is well formed, but something in it is not allowed where you put it. Common triggers: an attribute that does not belong on an element, an element nested inside one that cannot contain it, a value outside the permitted list, or a stray property on a spine itemref.
The text after the code is the actual instruction — read it literally. A message like “attribute X not allowed here” tells you precisely which attribute to remove or move. Fixes are almost always local: delete the offending attribute, re-nest the element, or correct the value. Fix one, re-run, and a surprising number of RSC-005 lines often collapse to a single root cause repeated across chapters.
Missing and remote resources
RSC-007 and RSC-001 mean epubcheck followed a reference — a stylesheet, image, font, or a spine entry — and could not find the target inside the container. The cause is nearly always a path or case mismatch: a href points to images/Cover.jpg but the file is images/cover.jpg, or a file was renamed while its reference was not. EPUB paths are case sensitive; fix the path or restore the missing file.
RSC-006 flags a remote resource — a URL pointing outside the EPUB. The spec only permits remote references for a narrow set of media, such as audio and video; everything else, including images, fonts, and stylesheets, must be packaged inside the container. The fix is to download the asset, add it to the manifest, and repoint the reference to the local copy.
The package document: OPF errors
OPF-* errors come from the .opf package document — the manifest, metadata, and spine. The most frequent: a file that exists in the container but is not declared in the manifest (or is declared but missing), a spine that references an id with no matching manifest item, or required Dublin Core metadata that is absent or malformed, such as a missing dc:identifier, dc:title, or dc:language.
Treat the OPF as the source of truth: every content file must appear once in the manifest with the correct media type, and every spine itemref must point to an existing manifest id. Add the missing declaration, correct the media type, or supply the required metadata value, and the cascade of downstream errors usually clears with it.
Markup, navigation and packaging
HTM-* errors mean the XHTML itself is malformed or uses something the spec disallows — an unclosed tag, an undeclared namespace, or a deprecated construct. Because EPUB content is XHTML, it must be well formed XML: every tag closed, every attribute quoted. NCX and navigation errors point at the table of contents — a broken link in the nav document, or a mismatch between the nav and the spine order.
PKG-* errors are about how the ZIP is assembled. The classic one: the mimetype file must be the first entry in the archive and stored uncompressed, with no extra bytes. If your zipping tool compressed it or reordered entries, epubcheck complains before it even reads your content. Re-package with the mimetype first and uncompressed — most EPUB export tools handle this automatically, so this usually means avoiding a manual re-zip.
The fix, step by step
-
1
Validate and read the raw report
Run your EPUB through epubcheck 5.x and capture the full output. Every line carries a code, a severity, and a file-and-line location — that triple is your map to the exact spot that needs a change. Do not guess; the report already names the file.
-
2
Sort by severity, blockers first
Separate errors from warnings. Errors break conformance and can stop reading systems from opening the book, so clear every one before you touch a single warning. Warnings are advisory and can wait until the errors are gone.
-
3
Fix by family, container outward
Group the findings — schema, resources, package document, markup — and start at the container: mimetype and packaging first, then the OPF, then the individual content files. Fixing a root cause often clears several lines at once.
-
4
Re-validate until the report is clean
Run epubcheck again after each batch of fixes. Codes cascade, so one correction can resolve or reveal others. Repeat until zero errors remain, then decide which warnings are worth clearing for your readers.