Why your EPUB was rejected, and how to fix each error

An EPUB is a website in a zip file. That is not a metaphor: it is a folder of XHTML documents, a stylesheet or two, the images, and a handful of XML files that describe what all of it is. It is packed in a specific order, with a specific compression setting on the first entry.

Almost none of the things that get a book rejected are about the book. They are about the archive, the manifest, and the markup underneath it, none of which you wrote, and all of which your software wrote for you.

The validator is the same one the retailer runs

Amazon, Apple, Kobo, Google and every aggregator between them check uploads with epubcheck, the reference validator maintained by the DAISY Consortium for the W3C. It is open source, it runs locally, and it is the same tool that will judge the file when you upload it.

So a rejection at the retailer is a slow, vague version of a message you could have read in a second on your own machine.

Versions drift. A distributor may be running a release a year or two behind the current one, so a file that passes locally can still meet an older complaint. More often, a file that passes an old validator on the retailer's side is not thereby correct.

Epubcheck reports at two severities:

• ERROR — the file violates the specification. It will be rejected. Fix it.
• WARNING — the file is legal but something is probably wrong. Read each one and decide.

A third category, INFO, is commentary. Ignore it.

Why a file that opens perfectly still fails

Nearly every EPUB reading application is built on a browser engine, and browser engines are built to repair broken markup rather than refuse it. Give one an unclosed tag, an attribute in the wrong place, or a file present in the archive but absent from the manifest, and it will paper over all three and show you a book that looks finished.

A validator does none of that repair, and neither does the next reading application, which may be an eight-year-old e-ink device with a stricter parser and no such generosity. The retailer validates because it has to sell a file that opens on hardware neither of you owns.

Your reading application is not evidence. It is the single most forgiving environment your file will ever be opened in.

The errors, in the order you will meet them

RSC-005, the most common rejection

ERROR(RSC-005): Error while parsing file: element "X" not allowed here

This is the general schema violation, and it accounts for most rejections. Some XML in the book does not match what the specification permits at that point. The message names the file, the line and the element, which is more than it sounds. The fix is nearly always visible on that line.

The usual causes, in rough order of frequency:

• An unclosed tag. XHTML is XML, so <br> and <img> must be <br /> and <img />, and every <p> needs its </p>. HTML forgives this. XHTML does not.
• An attribute that is not allowed there. A stray align, a name on an element that only takes id, a Word artefact that survived the conversion.
• Text directly inside an element that only takes elements. A loose sentence inside a <ul> rather than inside an <li>.
• A raw ampersand. & must be &. It is the single most common way a well-behaved title breaks a file.

OPF-014, OPF-015 and the manifest errors

ERROR(OPF-003): item ... is not listed in the manifest

The package document, package.opf, is the book’s inventory. Every file in the archive must be listed in it, and every file listed in it must exist in the archive. Both directions fail, and the second is the sneakier one: delete an image and forget the manifest line, and the book breaks.

Related, and frequent:

• OPF-014 — a document uses scripting, or MathML, or SVG, without declaring the corresponding property on its manifest entry.
• OPF-015 — a property is declared that the document does not actually use. Wrong in the opposite direction, and equally a failure.

The navigation document

ERROR(RSC-005): Missing nav element with epub:type="toc"

EPUB 3 requires a navigation document: an XHTML file with a <nav epub:type="toc"> inside it, and exactly one manifest entry carrying properties="nav". This is your table of contents, and it is not the same object as the page of contents a reader sees when they turn to the front of the book. One is structure the device reads; the other is a page you typeset.

The old EPUB 2 toc.ncx is deprecated and optional. Include it only if you have a specific reason to support very old hardware. If you do include it, it has to agree with the navigation document, because a validator will check that too.

PKG-007, the mimetype

ERROR(PKG-007): Mimetype file entry is missing or invalid

The first entry in the zip archive must be a file named mimetype, containing exactly application/epub+zip, with no compression and no trailing newline. It must be first, and it must be stored rather than deflated.

You cannot fix this by re-zipping a folder with the operating system’s own compression, which is exactly what most people try. The archive has to be built in that order, deliberately. If you are seeing PKG-007, the tool that produced the file is the problem, not the book.

HTM-004 and the encoding errors

Files must be UTF-8. A stylesheet or a document saved in Latin-1 or Windows-1252 will fail here, and the symptom that reaches a reader, before the rejection does, is a curly quote rendered as ’.

RSC-012, a link pointing nowhere

An internal link, a footnote reference or a contents entry points at a fragment identifier that does not exist in the target file. Common after a chapter is deleted or renamed late, and invisible in every reading application until someone taps the note and lands nowhere.

The warnings worth acting on

Not every warning is noise. Three are usually a real defect:

• A font that is not embedded. The book will render in whatever the device substitutes, which on many e-ink readers means the design you chose is simply not present.
• A remote resource. An image or stylesheet loaded over the network will be absent on a device reading offline, which is most of them, most of the time.
• An image with no alternative text. Legal, still a defect, and now a compliance problem. See below.

Accessibility is no longer optional

The European Accessibility Act applies from June 2025 and covers ebooks. Distributors selling into the EU now ask for accessibility metadata, and files without it are increasingly refused outright rather than merely marked down.

What is actually required is less onerous than it sounds. In the package document:

Metadata property	What it declares
schema:accessMode	How the content is perceived — textual, visual
schema:accessModeSufficient	Which combination is enough to read the whole book
schema:accessibilityFeature	structuralNavigation, tableOfContents, alternativeText
schema:accessibilityHazard	none, or a named hazard such as flashing
schema:accessibilitySummary	One human sentence describing the book’s accessibility

And in the content itself: a real alt on every image that carries meaning, an empty alt="" on every image that is decoration, the language declared with xml:lang, and headings that describe the structure rather than being chosen for their size.

The single most common accessibility failure is alt text written for a search engine rather than a reader. "Chapter 3 illustration" describes a file. "A woodcut of a hare running across a ploughed field" describes what a sighted reader receives.

Kindle needs a second check

Passing epubcheck gets you accepted at Amazon. It does not tell you what the book will look like, because KDP converts your EPUB into its own format after accepting it, and that conversion has its own opinions about embedded fonts, about CSS it will ignore, and about page breaks.

Open the accepted file in Kindle Previewer before you publish. It is free, it runs the conversion locally, and it shows you the book as the device will render it rather than as your validator approved it.

The order to work in

1. Run epubcheck locally. Fix every ERROR.
2. Read every WARNING and decide on each one, rather than clearing them reflexively.
3. Check the accessibility metadata is present and honest.
4. Open the result in Kindle Previewer if the book is going to Amazon.
5. Open it on a real device if you have one.

---

Most of these errors have one thing in common: they are produced at export, by a tool, out of a document that was never wrong. That is why the useful fix is usually not to edit the XHTML by hand but to correct whatever produced it. Hand-patching a file leaves the next export broken in exactly the same way.

It is also why the errors above are worth reading even if you never open an XHTML file. Knowing that PKG-007 means the archive was built wrong, and not that your book is wrong, is what tells you the problem is the tool.

Nueel builds the archive itself instead of zipping a folder, and writes the manifest and the navigation document out of the document model, which is the part most exports get wrong. It also runs a preflight check against the requirements of the shop you are exporting for before you export.

Common questions

What is epubcheck?

It is the reference validator for the EPUB format, maintained by the DAISY Consortium on behalf of the W3C. It is the same tool the retailers run on your file when you upload it, which is why a file that passes locally is very unlikely to be rejected for a structural reason. It reports two severities: errors, which break the specification, and warnings, which are legal but usually a mistake.

Why was my EPUB rejected when it opens fine on my computer?

Because a reading application is forgiving and a validator is not. Most EPUB readers are built on browser engines that repair broken markup silently, so a file with an unclosed tag or a missing manifest entry will often display perfectly on your machine and still fail validation. The retailer validates before it will sell the file, on the reasonable grounds that it has to open on devices neither of you has tested.

What does RSC-005 mean?

RSC-005 is the general schema violation: some XML in the book does not match what the specification allows at that point. The message names the file, the line and the element, and the fix is almost always in the markup rather than in the book. The most common causes are an unclosed tag, an attribute that is not permitted on that element, and text placed directly inside an element that only accepts other elements.

Does my EPUB need a table of contents?

Yes. EPUB 3 requires a navigation document, an XHTML file containing a nav element marked epub:type="toc", and the package manifest must identify exactly one file as that document. The older NCX file from EPUB 2 is optional now, and worth including only if you are targeting devices old enough to need it. A missing or malformed navigation document is one of the most common reasons a file fails.

Is EPUB accessibility now mandatory?

For books sold to readers in the European Union, yes. The European Accessibility Act applies from June 2025 and covers ebooks, so distributors selling into the EU now ask for accessibility metadata and increasingly reject files without it. In practice that means declaring accessMode, accessModeSufficient, accessibilityFeature and accessibilityHazard in the package document, giving every image a real alt text, and marking the language of the text.

Do I need to fix warnings as well as errors?

You have to fix errors, because they will stop the file being accepted. Warnings are worth reading rather than obeying blindly: some flag a genuine defect a reader will meet, such as a font that is not embedded or a remote resource that will not load offline, and some are noise about a practice you chose deliberately.

Which validator do the retailers actually use?

All the major distributors run epubcheck, though not always the same version and not always the latest. Amazon adds its own checks on top through Kindle Previewer, because a Kindle file goes through a further conversion after it is accepted. Passing epubcheck is necessary everywhere and sufficient almost nowhere, so a file bound for Kindle is worth opening in Previewer as well.