Readwyn 0.1.0

How to check an EPUB for errors

Run EPUBCheck, the free checker that Apple Books requires every submitted EPUB to pass. It's a W3C project that the DAISY Consortium maintains, and by its own account most retailers won't take a book that fails it. Download the zip from the project's releases page, unzip it, open Terminal in that folder and type java -jar epubcheck.jar yourbook.epub.

Installing it

The official download holds epubcheck.jar and a lib/ folder, and the installation guide says the two must stay together, so move the whole folder, not the jar alone. You also need Java. That guide still names Java 7, but the release notes made Java 8 or newer a requirement from the 5.0 series on. Type java -version to see what you have.

With Homebrew on a Mac, brew install epubcheck gives you an epubcheck command that works in any folder, and the formula carries the current release. The Ubuntu and Debian package is another matter. apt-get install epubcheck works, but at the start of November 2026 the oldstable, stable, testing and unstable suites of Debian and every Ubuntu release up to 26.10 still ship 4.2.6 (Debian's oldoldstable has the older 4.2.4). Version 4.2.6 is a build from June 2021 that checks the EPUB 3.2 rules. Volunteers look after those packages, not the project, as the installation guide points out.

The current release is 5.4.0, published on 15 September 2026; its release notes describe it as checking against EPUB 3.4, which in November 2026 was still a W3C Candidate Recommendation, not a finished standard.

There's no updater: you upgrade by replacing the folder with the new zip. If it crashes with a StackOverflowError, the troubleshooting page suggests a bigger Java thread stack, for example java -Xss1024k -jar epubcheck.jar book.epub.

You don't have to touch Terminal at all. The project's apps and tools page lists graphical front ends that run EPUBCheck for you, among them pagina EPUB-Checker for Windows, macOS and Linux, and ECheck for macOS, plus EPUBCheck plugins for calibre and Sigil. It also lists epubcheck.net, a website you upload the book to, and epubcheck-standalone, an experimental build compiled to JavaScript that checks the file inside your browser without uploading it.

The commands you'll use

epubcheck book.epub
epubcheck --mode exp book-folder/ --save
epubcheck -e book.epub
epubcheck --json report.json book.epub

The first line checks a finished file. A clean book ends with a count of 0 fatals, 0 errors, 0 warnings and 0 infos; anything else is listed with a code, the file inside the EPUB that has the problem, and usually a line and a column. The second line checks an unzipped book folder, which suits a book you're still editing, and --save then packs the folder into an .epub. With -e you see only errors and fatal errors; -u goes the other way and adds the minor “usage” notes that are hidden by default. The JSON (--json) and XML (-o) reports keep at most 25 copies of any one message unless you add --maxOfEachMessage unlimited; there's also an XMP report (-x). The command line reference lists every option.

In a script, watch the exit status. EPUBCheck returns 1 only when it reports an error and 0 when it finds nothing worse than warnings, so add --failonwarnings if a warning should stop your build.

Errors, warnings and the rest

Every message starts with its severity, and the messages reference ties the two that matter to the wording of the EPUB specification. An error means the book breaks a requirement written as MUST, MUST NOT or REQUIRED. A warning means it ignores a recommendation, written as SHOULD, SHOULD NOT or RECOMMENDED. A fatal error means EPUBCheck couldn't read any further; the reference puts that down to a bug in the checker or to a condition it didn't foresee, such as an I/O error. Info and usage messages are notes about the book, not faults.

The project's guide to running it takes a line like this one apart: ERROR(RSC-001): ./book.epub(-1,-1): File "EPUB/missing.xhtml" could not be found. Look the code up in the messages reference. The numbers in brackets are the line and column, and -1,-1 means the problem has no single place in a file, as with a file that isn't there at all.

A pass says nothing about the writing. EPUBCheck's introduction lists what it inspects (the container, the package file and its metadata, the markup, and the links between files) and says it won't catch typos or the wrong picture.

Some codes and their fixes

PKG-006 (the messages reference writes this and some other codes with an underscore, PKG_006) says the mimetype file is missing or isn't the first entry in the zip. The EPUB 3.3 specification requires that file to come first, uncompressed, containing nothing but application/epub+zip with no spaces or line break around it. If you repack a book folder by hand, let EPUBCheck do the packing with --mode exp --save. (What is inside an EPUB file covers the rest of the container.)

RSC-005 reads “error while parsing file” and is followed by the real complaint from the schema, such as an attribute that isn't allowed on an element. The text after the colon is the part to fix.

RSC-007 means a page refers to an image, stylesheet or chapter that isn't in the EPUB. Its neighbour RSC-008 means the file is there but missing from the manifest in the package file. RSC-012 is a link to an #anchor that no element in the target page carries, and NCX-001 means the identifier in the NCX (the older table of contents file) differs from the one in the package file.

File names get smaller flags. PKG-010 is a warning about a space in a name, and PKG-012, a usage note, is about letters outside ASCII; the messages reference says either can trip up older reading systems.

Which stores ask for a pass

Apple's publishing guide asks for the most recent version of EPUBCheck, which at the time of writing means 5.4.0, not the 4.2.6 that apt-get installs or a zip you unpacked a few years ago. Google's Play Books partner help tells publishers to run EPUBCheck before uploading and shows processing errors under the book's Content tab in Partner Centre; it takes EPUB 2 and EPUB 3, and prefers 3.3.