EPUB Validation: How to Pass EPUBCheck (2026)

You have exported your manuscript as an EPUB and it opens perfectly in your e-reader — so it must be ready to upload, right? Not necessarily. An EPUB is not a single document the way a Word file is. As our EPUB vs MOBI vs PDF breakdown explains, an EPUB is a zipped package of dozens of files — XHTML chapters, stylesheets, images, fonts, and a package document that lists them all — and every one must follow the EPUB specification exactly. A book that looks fine on your device can still carry structural problems that make retailers reject it. EPUB validation is how you find out before your readers do.

This guide walks you through EPUB validation in 2026: what EPUBCheck is, how to run it three different ways (including a free drag-and-drop app), how to read its error report, and how to fix the most common failures.

What EPUBCheck Actually Is (and Isn’t)

EPUBCheck is the official conformance checker for EPUB publications — open source, originally created by the IDPF and now maintained by the DAISY Consortium for the W3C. It checks your EPUB against the EPUB 3.3 specification (latest release v5.4.0, September 2026). Think of it as a spell-checker for your book’s structure rather than its words: it opens the .epub (really a ZIP archive), reads every chapter, stylesheet, image, and font inside, and verifies each against the spec. Every deviation is reported as a message with a code, a severity, and a file-and-line location.

What it is not: a quality judge or a repair tool. It cannot tell you whether your typography looks good — only whether the file conforms — and it never modifies your file. Every fix still happens in your manuscript or your export settings.

Why a Clean Validation Report Matters in 2026

A valid EPUB is the ticket that gets your book into stores. Amazon KDP converts your EPUB into Kindle format on upload, and structural errors are the leading cause of the cryptic “there are issues with your content” emails our Kindle upload error guide walks through. Apple Books is stricter still: it routinely refuses EPUBs that KDP accepted with a shrug, which is why validating before the Apple Books upload saves real time.

Aggregators raise the stakes further. Draft2Digital, IngramSpark, and library distributors run their own checks — largely the same conformance rules repackaged — and most reject files that fail. A clean EPUBCheck report is the closest thing to a guarantee your file will pass those gates.

There is a subtler reason: silent corruption. An EPUB with errors does not always get rejected — sometimes it uploads fine and then renders wrong for some readers. A chapter that falls out of reading order, an image that shows on iPads but not on Kobo, a table of contents that skips chapters — these are symptoms of validation errors that slipped through. An hour with EPUBCheck before launch is dramatically cheaper than fixing them after publication.

Three Ways to Run EPUBCheck

All three routes use the same official engine underneath.

The easiest route: Pagina EPUB-Checker. This free app from the German publisher-services company Pagina wraps EPUBCheck in a graphical interface for Windows, Mac, and Linux. Download it from the company’s website, drag your EPUB onto the window, and it runs the full check. No installation needed — it even runs from a USB stick — and it can validate expanded (unzipped) EPUB folders too.

The no-install route: the W3C online validator. The W3C hosts a web version of EPUBCheck where you upload your file and get the report in the browser. Perfect for a one-off check or a borrowed computer — but your file is uploaded to someone else’s server, so skip it for unpublished manuscripts you want to keep private.

The power-user route: the command line. EPUBCheck is a Java program: download the latest release from its GitHub releases page, make sure Java is installed, and run java -jar epubcheck.jar your-book.epub. A clean file prints “Validating using EPUB version 3.3 rules. No errors or warnings detected. Messages: 0 fatals / 0 errors / 0 warnings / 0 infos.” — the finish line for this entire guide. Useful flags include -j report.json for a JSON report and -e for errors only. If Java is the obstacle, community builds compile EPUBCheck to plain JavaScript, so npx epubcheck-standalone-cli your-book.epub runs the same checks from Node.js.

How to Read the Report: Severities and the Summary Line

EPUBCheck sorts every finding into five severity levels. A fatal error stops the check entirely — something is so broken that EPUBCheck cannot continue. Fix these first.

An error violates a MUST rule of the specification: a required element is missing, a value is illegal, a file is referenced but absent. Most retailers reject files with errors, and every one must be fixed.

A warning violates a SHOULD recommendation — best practice, not a hard rule. A file with only warnings can still upload, but treat warnings as errors during your own pass, because the retailer that rejects you will not distinguish.

Info and usage messages are milder notes (usage is hidden by default unless you pass -u). Every message carries a code (like RSC-007 or CSS-008), a location (file, often with line and column), and a plain-language description. Work the report top to bottom: one root cause often produces a cascade of secondary messages, and the cascade vanishes when the root is fixed. A single missing image referenced on twenty pages produces twenty RSC-007 errors — all twenty die when the image is restored.

The Missing-File Errors: RSC-007 and RSC-008

These two are the most common EPUBCheck failures, and they are two sides of the same coin: the file list in your package document does not match the files actually inside the EPUB.

RSC-007: “Referenced resource could not be found in the EPUB.” Something in your book points at a file that is not in the package. The classic cause is an image: you deleted or renamed chapter-3-diagram.png in your source folder, but the chapter still links to it. Restore the missing file under the exact name the link expects, or remove the link, then re-export.

RSC-008: “Referenced resource is not declared in the OPF manifest.” The mirror image: the file is physically inside the EPUB, but the package document (the .opf file) does not list it in its manifest. Every resource must be declared — chapters, images, fonts, stylesheets, the navigation document, everything. This usually happens when an EPUB is hand-assembled or an export tool glitches: the file was copied into the archive but the manifest was not updated. Declare the file in the manifest with the correct media type, or delete the stray file if it is not used.

One more gotcha: case sensitivity. The EPUB archive is case-sensitive, so Images/Cover.jpg and images/cover.jpg are different files. Everything works on Windows (case-insensitive filesystem), then RSC-007 appears when the file reaches a retailer’s Linux server. Match filename case exactly between links and actual files.

Packaging Errors: the Mimetype File and the OPF

Before EPUBCheck reads your chapters, it inspects the container — and the humble mimetype file causes a surprising share of failures. An EPUB must start its ZIP archive with a file named exactly “mimetype”, stored uncompressed, containing exactly the text application/epub+zip. ZIP tools that reorder or compress the archive trigger PKG-006 (mimetype missing or not first), PKG-005 (illegal extra field), or PKG-007 (wrong content). If you ever zip an EPUB by hand with a generic archiver, expect one of these. The cure: never hand-zip — export from your EPUB tool instead.

The OPF — the package document, usually content.opf — is the next checkpoint. It holds the metadata, the manifest (the file list from the previous section), and the spine (the reading order). OPF-001, an error parsing the file, means the XML itself is malformed — an unescaped ampersand in a title, a missing closing tag. Open the OPF in a text editor, fix the syntax at the reported line, and revalidate. If the OPF is missing entirely, you get OPF-002, a fatal error — re-export rather than patch.

Metadata and Navigation Failures

Metadata errors are quiet: they rarely break rendering, but they fail strict checks. EPUB 3 requires a small set of Dublin Core metadata in the OPF: dc:title (the book’s title), dc:identifier (a unique ID for the edition, typically your ISBN or a UUID), dc:language (like en), and a dcterms:modified timestamp. Leave any out — or leave placeholder text like “Untitled” — and EPUBCheck reports an error. Fill every field deliberately in your tool’s metadata panel, and make the identifier genuinely unique per edition.

Then the navigation. EPUB 3 uses the Navigation Document — a special XHTML file (usually nav.xhtml) holding the table of contents — which must be declared in the manifest with the nav property and included in the spine. Classic failures: the nav file exists but was left out of the spine, a new chapter was never linked from the nav, or nav links point at renamed files (hello again, RSC-007). If your table of contents skips chapters on a device, the nav document is the first suspect.

CSS and Image Failures

CSS-008 — “An error occurred while parsing the CSS” — means your stylesheet has a syntax problem: an unclosed brace, a stray semicolon. The report names the file and line; open it, look at that exact spot, and fix the syntax. EPUB CSS is a restricted subset, so keep it simple.

Two encoding traps follow. CSS-003 warns that your stylesheet is UTF-16 instead of UTF-8: re-save it as UTF-8. CSS-001 errors when the stylesheet uses the direction or unicode-bidi properties, which EPUB forbids — use the HTML dir attribute instead. Fonts must be TrueType, OpenType, WOFF, or WOFF2 (CSS-007 notes anything else), and every font must be in the manifest.

Images fail in three familiar ways. First, the missing-or-undeclared pair — an image link is the single most common RSC-007 in real books. Second, format: an img element must reference a core media type (JPEG, PNG, GIF, SVG); anything exotic triggers MED-003, and a corrupted header triggers MED-004 — re-export as a clean JPEG or PNG. Third, size: gigantic print-resolution images bloat the file and can crash low-memory e-readers, so downsample photographs to sensible eBook dimensions before export.

The Pre-Validation Checklist

Work this list before every validation run:

• Every image referenced in the text exists in the EPUB, with matching filename case.
• Every file in the EPUB is declared in the OPF manifest — chapters, images, fonts, stylesheets, nav.
• The mimetype file is first in the archive, uncompressed, containing exactly application/epub+zip (never hand-zip; export from your tool).
• Metadata is complete: dc:title, dc:identifier (unique per edition), dc:language, dcterms:modified.
• The navigation document is declared with the nav property and included in the spine; every chapter appears in the TOC.
• Stylesheets are UTF-8, parse cleanly, and avoid forbidden properties like direction and unicode-bidi.
• All fonts are TrueType, OpenType, WOFF, or WOFF2, and every font is in the manifest.
• All images are JPEG, PNG, GIF, or SVG — no exotic formats, no corrupted files, sensible dimensions.
• No remote resources: every image, font, and stylesheet lives inside the EPUB.
• Special characters in the OPF are escaped — especially & as &.

Run EPUBCheck, fix errors top-down, and re-run until the report reads “No errors or warnings detected.” Then open the validated file in two different reading apps and spot-check the cover, table of contents, and any pages with images or tables. Validation proves the structure is legal; your eyes prove it looks right.

Still stuck? Copy the message code (RSC-007, CSS-008, PKG-006 — whatever it says) into a search engine with “EPUBCheck”: the W3C maintains a full message reference for every code, and the MobileRead forums hold a decade of threads on the same problems.

Conclusion: Make Validation a Habit, Not a Rescue Mission

EPUB validation feels like bureaucracy until the day it saves your launch. Run EPUBCheck — with the Pagina app, the online validator, or the command line — read the report by severity, fix errors from the top down, and do not ship until the summary line reads “No errors or warnings detected.” The failure families in this guide — missing files, manifest mismatches, broken packaging, bad metadata, navigation gaps, stylesheet errors, and image problems — cover the overwhelming majority of real-world reports. Validate every revision, and the upload step becomes the boring formality it should be.