EPUBCheck Errors Explained: What Each One Means and How to Fix It
A plain-English reference for the EPUBCheck errors indie authors actually hit — RSC-005, RSC-001, OPF-003, PKG-006 and more — with what causes each and how to fix it.
EPUBCheck is the official validation tool for the EPUB format, maintained by the W3C. Retailers run it — or something close to it — when you upload a book. When it fails, it hands you something like this:
ERROR(RSC-005): book.epub/OEBPS/chapter3.xhtml(42,18):
Error while parsing file: element "i" not allowed here
That is written for developers. This page translates the errors indie authors actually hit into plain English: what each one means, what caused it, and what to do about it.
A note on honesty up front: some of these are genuinely fixable in a few minutes. Others require editing the internals of the file, which is not reasonable to expect of most authors. This guide says which is which rather than pretending everything has a tidy manual fix.
How to read an EPUBCheck message
Every message follows the same shape:
ERROR(RSC-005): book.epub/OEBPS/chapter3.xhtml(42,18): [description]
│ │ │ │
│ │ │ └─ column
│ │ └──── line number
│ └───────────────────────────── which file
└──────────────────────────────────────────── the error code
ERROR stops your book being accepted. WARNING usually will not, though some retailers are stricter than others. INFO is advisory.
The prefix tells you which part of the book is at fault:
| Prefix | Area |
|---|---|
PKG | The EPUB container itself — the ZIP and its required files |
OPF | The package document, which lists your files and reading order |
RSC | Resources — missing files, broken references, markup problems |
NAV | The table of contents |
HTM | Chapter markup |
CSS | Stylesheets |
ACC | Accessibility |
Container errors (PKG)
These mean the file is not assembled correctly as an EPUB. They almost always come from a file that was unzipped, edited by hand, and rezipped with ordinary ZIP software.
PKG-003 / PKG-004 — the file could not be read as an EPUB
An EPUB is a ZIP archive with a specific structure inside. This error means the file could not be opened as one at all.
Usual causes: the file was renamed rather than exported (a .docx renamed to
.epub is still a Word document), or it was truncated during a transfer.
Fix: re-export or re-download the original. If you renamed a file, that will never work — the formats are unrelated.
PKG-006 / PKG-007 — mimetype missing, out of place, or wrong
Every EPUB must contain a file named mimetype as the very first file in the
archive, stored uncompressed, containing exactly application/epub+zip and
nothing else — no line break, no byte order mark. PKG-006 means the file is
missing or isn’t first; PKG-007 means its contents are wrong.
Usual cause: the book was unzipped and rezipped. Standard ZIP tools compress everything and reorder files, which breaks both requirements.
Fix by hand: not realistically. Getting this right means creating the archive with the mimetype stored first and uncompressed, which normal ZIP software will not do for you.
Fix properly: re-export from a tool that builds the container correctly.
RSC-002 — META-INF/container.xml is missing
container.xml is the file that tells a reader where to find your book’s
package document. Without it, nothing can locate your content.
Fix by hand: not realistically. Fix properly: re-export.
Package document errors (OPF)
The package document (.opf) lists every file in your book and the order
chapters are read in. These errors mean that list is wrong.
RSC-003 / OPF-002 — the package document is missing or unreachable
Either container.xml does not declare where the package document is (RSC-003),
or it points at a file that is not there (OPF-002).
Fix by hand: not realistically. Fix properly: re-export.
An empty spine
The spine is the ordered list of chapters. If it is empty, readers open the file and show nothing.
Fix by hand: not realistically. Fix properly: re-export.
RSC-001 / RSC-007 — a referenced file is missing
The book refers to a file — usually an image — that is not actually inside the EPUB. RSC-001 means a file could not be found at all; RSC-007 means a chapter points to an image or other resource that is missing.
Usual causes: an image was deleted after the book was built, or a filename
changed case. Cover.jpg and cover.jpg are different files on most systems,
and this catches people constantly when moving between Windows and Mac.
What readers see: a broken-image placeholder where your picture should be.
Fix by hand: possible with an EPUB editor if you still have the missing file.
Fix properly: re-export, making sure every image is present first.
OPF-003 — a file is in the EPUB but not listed
The opposite problem: a file sits inside the EPUB but the package document doesn’t list it. This is usually a warning rather than an error.
Usual causes: hidden system files that got zipped up by accident, such as
macOS’s .DS_Store or Windows’ Thumbs.db, or an old image left behind after
editing.
Fix by hand: possible with an EPUB editor — delete the stray file.
Fix properly: re-export, which only packs the files the book uses.
Markup errors (RSC-005 and friends)
This is the most common category by a wide margin, and the one authors coming from Word hit hardest.
RSC-005 — error while parsing file
The single most-searched EPUBCheck error, and unhelpfully generic: it means a chapter file is not valid XHTML. The detail after the code is what matters.
EPUB requires XHTML, which is far stricter than the HTML a web browser will happily forgive.
Common variants:
“element X not allowed here” — a tag is somewhere the specification does not
permit, often a block element such as <div> or <p> nested inside an inline
element like <i> or <span>. Frequently produced by Word exports where
italics run across a paragraph break.
“element type X must be terminated” — an unclosed tag. HTML tolerates a
missing </p>; XHTML does not.
“attribute X not allowed” — leftover attributes from a word processor.
Word exports are notorious for <p class="MsoNormal"> and inline styles that
EPUB does not accept.
“The entity name must immediately follow the ’&’” — a bare ampersand. In
XHTML, & must be written &. This appears the moment you write “Smith &
Sons” and export from a tool that does not escape it.
Fix by hand: possible in Sigil or Calibre’s editor if you are comfortable reading XHTML, working file by file to the line numbers given.
Fix properly: re-export from a tool that generates clean XHTML. Markup problems do not survive a proper rebuild, which is why this error effectively disappears when you stop converting Word files directly.
Metadata errors and warnings (OPF / META)
Missing dc:language — the Kobo trap
This one deserves special attention because it is a very common reason a file passes on Amazon KDP and fails on Kobo.
Every EPUB must declare its language in the package metadata, and EPUBCheck reports it as an error when it is missing. KDP is permissive and will often accept a file without it. Kobo enforces it, and so does Apple Books. Authors upload to Amazon, see it succeed, upload the identical file to Kobo, and get a rejection with no obvious explanation.
It also affects hyphenation and text-to-speech, so it matters beyond validation.
Fix by hand: genuinely easy. Open the book in Calibre, edit the metadata, set the language, and save. Two minutes.
Fix properly: set it once in your formatting tool so every export carries it.
Missing title, author, or identifier
The metadata inside the file is separate from what you type into a retailer dashboard. When it is missing, your book shows up as “Unknown” in a reader’s library.
The identifier (an ISBN or UUID) distinguishes this book from every other, and matters when you upload an updated version of an existing title.
Fix by hand: all three are editable in Calibre’s metadata panel.
Navigation errors (NAV)
No table of contents
EPUB 3 uses a navigation document; EPUB 2 used a file called toc.ncx. A book
needs at least one, and including both gives the widest compatibility across old
and new readers.
What readers see: no chapter list and no way to jump between sections. Most retailers require a working table of contents.
Fix by hand: not realistically — the navigation document has to match your actual file structure.
Fix properly: re-export from a tool that generates both formats.
Accessibility warnings (ACC)
These are warnings rather than errors in most cases, but they are becoming more important: the European Accessibility Act has applied to ebooks sold in the EU since June 2025.
Images without alt text
Every meaningful image needs a text description for readers using screen readers.
This one cannot be automated. No tool can invent a meaningful description of your map, your chapter ornament, or your author photo. Re-exporting will not fix it. A person has to write the words.
A good formatting tool will show you every image missing a description and handle the markup once you have written them — but the writing is yours.
Missing language on content documents
Separate from the package-level language, each chapter file should declare its language too. Screen readers use it to choose pronunciation.
Fix by hand: not realistically across a whole book. Fix properly: re-export.
Which of these can you actually fix yourself?
Being straight about this, because most guides are not:
| Realistically fixable by hand | Needs the file rebuilt |
|---|---|
| Missing language, title, author, identifier (Calibre, ~2 minutes) | Container and mimetype errors |
| Individual markup errors, if you can read XHTML | Missing or broken package document |
| Removing competitor store links | Empty spine, missing navigation |
| Writing alt text (only you can do this) | Widespread markup problems |
The pattern: metadata is easy, structure is not. If EPUBCheck is complaining about a missing language, fix it in Calibre and move on. If it is complaining about the container, the package document, or dozens of markup errors across every chapter, hand-editing is not a good use of your time.
Check your file before you upload
You do not need to wait for a rejection email to find out whether your book has these problems.
Our free EPUB checker reads your file in the browser — nothing is uploaded — and reports what it finds with the same plain-English explanations used above. It also shows a per-retailer view, so you can see at a glance whether KDP, Kobo, and Apple Books are each likely to accept the file.
It is a preflight rather than a full EPUBCheck run, and we say so on the page. It catches the problems that cause most rejections; the official EPUBCheck tool from the W3C is more exhaustive.
If the problems are structural, importing your EPUB into Libba and exporting it again resolves them — your chapters and structure come across, and the broken markup underneath is regenerated cleanly.
Error codes checked against EPUBCheck’s official message list in October 2026. Validation behaviour changes over time — check each retailer’s current guidance before publishing.
Related guides
- Why Your EPUB Gets Rejected by Kobo (But Not KDP) — the language trap in detail
- Why Your EPUB Gets Rejected by KDP — Amazon-specific causes
- Why Your Word Document Looks Terrible as an Ebook — where markup errors come from
- What is EPUB Validation? — the wider picture
