typesetting.ai
← Writing

What EPUBCheck errors actually mean

30 August 2026 · 5 min read

EPUBCheck is the reference validator for the EPUB format, maintained by the DAISY Consortium on behalf of the W3C. It is the tool the standard is checked against, and something very like it runs when you upload a book to a store. Its output is precise, thorough, and written for people who already know what an OPF file is.

Here is what the common messages are actually telling you.

First: errors, warnings, and what blocks a book

EPUBCheck sorts its findings by severity, and the distinction matters more than the count.

FATAL means it could not read the file at all. Usually the EPUB is not a valid zip archive — a truncated download, or something that renamed a folder to .epub and hoped.

ERROR means the file breaks the specification. These are what get a book rejected, and they are the ones to fix.

WARNING means something is legal but probably unintended. Warnings rarely block publication. They are worth reading because they often point at something that will look wrong on a device, but a book with warnings and no errors is publishable.

A long list is usually one cause. Two hundred errors across forty chapters is not two hundred problems — it is one structural mistake repeated in every chapter file, and fixing the root clears the list.

The messages you are most likely to see

RSC-005: element "metadata" incomplete; missing required element "dc:title"

Something required is missing from the package document — the file that describes the book to the reader. dc:title and dc:identifier are the usual casualties.

This is almost never something you did. It is a converter that did not know what to put there, because nothing in your Word file said "this is the title". Supplying a title and author before conversion, rather than after, is the fix.

RSC-005, other forms

RSC-005 is a general "this file does not match the specification" and its message text is the useful part. The wording after the code tells you the element and the file. Read that rather than the code.

OPF-014 / OPF-015: the spine and the manifest disagree

Every document in an EPUB has to be declared in the manifest and ordered in the spine. These say a file is in one and not the other.

In practice: a chapter exists but the book does not know to show it, or the book refers to a chapter that is not there. Readers see a missing chapter or a dead navigation entry.

RSC-007: referenced resource could not be found

A link, image or stylesheet points at something that is not in the file. Broken internal links usually come from a hand-built contents page whose targets moved. Missing images usually come from a converter that referenced them and did not package them.

NAV-003 / the navigation document

EPUB 3 requires a navigation document — the machine-readable table of contents that drives the Go To menu. Errors here mean it is absent, malformed, or does not match the book's structure.

This is the difference between an ebook you can navigate and one you can only scroll. It is also the single most common thing missing from a file produced by "export as EPUB" in a word processor, because nothing in the source document declared what a chapter was.

HTM-xxx: the XHTML is not well-formed

EPUB content is XHTML, which is stricter than the HTML a browser forgives. An unclosed tag that a browser silently repairs is an error here.

Not your problem to fix by hand. It is a signal the file was assembled by something careless.

PKG-xxx: problems with the package itself

The zip is wrong. The most particular rule: the mimetype file must be the first entry in the archive and must be stored uncompressed. Rezip an unpacked EPUB with an ordinary zip tool and you will break this, which is why "just unzip, edit, rezip" fails so often.

ACC-xxx: accessibility

Missing alt text, missing language declarations, missing accessibility metadata. These are usually warnings rather than errors, and they are the ones most worth caring about beyond compliance: they are what a screen reader needs.

What actually causes most of them

Almost every error above comes from the same place, and it is not the author.

A Word document has no structure. It has styling — this line is 16pt bold and centred — and nothing in it says "this is chapter four". An EPUB is the opposite: a set of documents with declared relationships and a navigation map. Converting means inferring the second from the first, and a converter that skips that step produces a file that is technically an archive of your words and structurally not a book.

So the errors cluster around structure: missing navigation, spine and manifest disagreements, dead links in a contents page that was typed rather than generated.

Checking your own file

You can run EPUBCheck yourself — it is a Java command-line program, freely available. If you would rather not install Java to answer one question, our EPUB validator runs the same tool on a file you upload and shows you the messages with their locations. It is free, there is no limit, and the file is checked and discarded rather than stored.

If the list is long and structural, rebuilding from your original manuscript is usually faster than patching. Our EPUB formatter validates every file it produces before you download it, so the check happens before the store does it rather than after.

The thing worth remembering

Valid is not the same as good. EPUBCheck can tell you the file conforms to the specification. It cannot tell you the chapter breaks fall in sensible places, or that the book reads well on a phone at large type. It rules out the category of problem that gets a file rejected — which is worth a great deal, and is not everything.