EPUBCheck is the reference validator for EPUB files, and retailers use it as a gate. Its messages are terse and code-prefixed, which makes them look more alarming than they are. Most failures come from a handful of requirements, and each code maps to a specific rule in the EPUB 3.3 specification.
One thing to know before you start: no authoritative "most common errors" list exists. Neither the W3C nor the EPUBCheck project publishes ranked frequency data, and its troubleshooting page carries only two entries, neither of which is a validation error. What follows is organised by which specification requirements are most often broken, not by counted frequency.
Errors and Warnings Are Not the Same
EPUBCheck's own severity definitions are precise, and they matter for deciding what you must fix:
- Error: "A failure to match an EPUB conformance requirement. In the EPUB specifications, these requirements are identified with 'MUST', 'MUST NOT', or 'REQUIRED' keywords."
- Warning: "A deviation from an EPUB recommended practice… identified with 'SHOULD', 'SHOULD NOT', or 'RECOMMENDED' keywords."
- Fatal Error: "An error which prevents EPUBCheck from further processing the content."
So errors are conformance failures and must be fixed. Warnings are advisory. Retailers vary in how strictly they enforce warnings, and Google's stated requirement is simply that the file "must be validated by EpubCheck" without naming a severity threshold.
One notational quirk: the codes are written with underscores in EPUBCheck's own documentation (RSC_005) but printed with hyphens on the command line (ERROR(RSC-005)). They are the same message.
The Codes You Will Actually Meet
RSC-005, "Error while parsing file" The most common and least informative code. It is a generic schema validation failure, and the real complaint is in the text appended after it. Usually it means your XHTML is not well formed or an element is not allowed where you put it.
The underlying cause is often a misunderstanding: EPUB content documents are XHTML, not HTML. The specification requires that a content document "MUST be an [html] document that conforms to the XML syntax". That means void elements must be closed (<br />), ampersands escaped, and tags properly nested. Markup a browser forgives will fail here.
RSC-016, "Fatal Error while parsing file" The same problem, worse. The XML is malformed enough that parsing stops.
RSC-007, "Referenced resource could not be found" A link, image or stylesheet points at a file that is not there. Usually a rename, a wrong relative path, or a case mismatch. EPUB paths are case sensitive even when your operating system is not, which is why a file can work locally and fail validation.
RSC-008, "Referenced resource is not declared in the OPF manifest"
The file exists but is not listed in the package document. The specification requires that the manifest "MUST list all publication resources". Add an item entry.
OPF-003, "Item exists in the EPUB, but is not declared in the OPF manifest" The inverse, and only a warning: a file is sitting in the container that nothing references. Usually a leftover.
RSC-012, "Fragment identifier is not defined"
A link to #something where no element has that id. Common after restructuring, and a frequent cause of broken contents pages.
PKG-006, "Mimetype file entry is missing or is not the first file in the archive" and PKG-007, "Mimetype file should only contain the string 'application/epub+zip' and should not be compressed" These two are the classic zipping mistake, and they are the reason you cannot simply right-click a folder and compress it. See below.
HTM-004, "Irregular DOCTYPE"
EPUB 3 expects <!DOCTYPE html>. An old XHTML 1.1 doctype carried over from an EPUB 2 file triggers this.
NCX-001, "NCX identifier does not match OPF identifier"
If you include a legacy toc.ncx for old reading systems, its dtb:uid must equal the dc:identifier in the package document. They drift apart when an identifier is changed in one place only.
OPF-014 / OPF-015, property should or should not be declared
Manifest items need properties such as scripted, svg, mathml or remote-resources declared when used, and not declared when unused.
The Mimetype Rule, Because It Causes Most Zipping Failures
The specification is unusually strict here, and every clause is a MUST:
"EPUB creators MUST include the
mimetypefile as the first file in the OCF ZIP container… The contents of themimetypefile MUST be the MIME media type stringapplication/epub+zipencoded in US-ASCII. Themimetypefile MUST NOT contain any leading or trailing padding or whitespace. Themimetypefile MUST NOT begin with the Unicode byte order mark U+FEFF. EPUB creators MUST NOT compress or encrypt themimetypefile. EPUB creators MUST NOT include an extra field in its ZIP header."
Five separate requirements on one nineteen-byte file. Ordinary archive tools violate at least one, usually by compressing it, reordering entries, or adding an extra field. This rule has been unchanged since EPUB 2.
Everything else in the container may be compressed normally. The common belief that an EPUB must be zipped uncompressed throughout is wrong.
Things That Are Not Errors
Several widely repeated requirements are not in the specification:
- A cover image is optional. Recommended, but the spec says setting it is "OPTIONAL". Retailers require covers as a store rule.
- An NCX is not required. It is a legacy feature for EPUB 2 compatibility, and the spec advises considering whether old devices are worth the effort. Only the navigation document is mandatory, which is a genuine requirement and the reason even a novel needs a table of contents in its ebook.
- Author, publisher, date and subject are optional. Only four metadata items are required:
dc:title,dc:identifier,dc:languageanddcterms:modified. See ebook metadata explained. - A
rendition:layoutdeclaration is optional. Its absence means reflowable, which is the default and what a novel wants. See reflowable vs fixed layout.
What Deckle Produces
Deckle builds the container itself rather than zipping a folder, so the mimetype rules are handled: the file is written first and stored uncompressed, which is exactly what PKG-006 and PKG-007 check.
The four required metadata items are all written, including dcterms:modified in the precise form the spec demands, an ISO 8601 UTC timestamp ending in Z. Deckle also emits a legacy toc.ncx alongside the navigation document, which is permitted and harmless.
If a Deckle EPUB fails validation, the likely causes are content rather than container: an image that could not be embedded, or a broken internal link. The export warnings after a compile name the document responsible.
Common Mistakes
- Zipping the folder with an ordinary archive tool. The mimetype file has five separate requirements that most tools break.
- Treating warnings as failures. Warnings map to SHOULD-level advice.
- Writing HTML instead of XHTML. Unclosed tags and raw ampersands cause most RSC-005 reports.
- Ignoring case in filenames. EPUB paths are case sensitive.
- Adding an NCX because a tutorial said EPUB needs one. It is legacy and optional.
- Reading RSC-005 as the whole message. The actual fault is in the text after the code.
FAQ
Q: Do I have to fix every warning? A: No. Warnings are recommendations. Errors are conformance failures and must be fixed.
Q: Why does my EPUB work in my reader but fail validation? A: Reading systems are forgiving; the validator is not. A file can render correctly and still break MUST-level rules.
Q: What is the single most common cause of failure? A: There is no published frequency data. In practice, malformed XHTML and mimetype zipping errors account for a large share.
Q: Does passing EPUBCheck guarantee a retailer accepts my file? A: No. Retailers add their own requirements on top, and some, such as Amazon, document proprietary behaviour that differs from the spec.
Q: Where do I get EPUBCheck? A: It is maintained by the W3C. Many tools embed it, and Amazon's Kindle Previewer performs its own checks before upload.