Free guide — no signup

epubcheck errors, explained in plain English

epubcheck is the official validator for EPUB files, maintained under the W3C. It checks your book against the EPUB specification and reports every violation as a code — RSC-005, OPF-014, PKG-006 — followed by a message that is often more cryptic than the problem deserves. It matters because the major retailers lean on EPUB validity: Amazon KDP, Apple Books, and Kobo all expect a well-formed EPUB, and an invalid file is how you get upload rejections, silent conversion glitches, and broken layouts on devices you never tested.

To run it yourself, download the latest release and run java -jar epubcheck.jar book.epub (it needs a Java runtime), or use one of the free web front-ends that host epubcheck online — several ebook services offer one. Then look your codes up below.

First: errors vs. warnings — what actually blocks you

epubcheck reports at four severities. FATALmeans the file couldn’t even be processed — usually it isn’t a valid ZIP or the package document is unreadable. ERROR is a violation of the EPUB specification. WARNING flags something legal-ish but suspicious, like undeclared extra files. USAGE is advisory nit-picking, hidden unless you ask for it.

Retailers don’t publish an exact mapping to epubcheck codes, but the practical pattern is consistent: files with fatals and errors get rejected at upload or mangled during conversion, while warnings usually pass. Treat every error as a must-fix and warnings as strongly-should-fix — a clean report is the only result that removes all guesswork across KDP, Apple, and Kobo.

Package errors (PKG & OPF)

These come from the EPUB container itself — the ZIP structure, the mimetype file, and the OPF package document that declares every file in the book.

PKG-006

Mimetype entry missing or is not the first file in the archive.

What it means: An EPUB is a ZIP file with one strict rule at the top: the very first entry must be a file named mimetype, stored without compression. This error means the file is missing, isn’t first, or was compressed — which almost always happens when someone unzips an EPUB, edits it, and re-zips it with a normal ZIP tool.

How to fix it: Rebuild the archive with the mimetype file added first and uncompressed. On the command line: zip -X0 book.epub mimetype, then zip -rg book.epub META-INF OEBPS. Editors like Sigil and Calibre handle this automatically, which is why the error usually only appears after hand-editing.

PKG-007

Mimetype file should only contain the string 'application/epub+zip' and should not be compressed.

What it means: The mimetype file exists but its contents aren’t exactly right. The file must contain the ASCII string application/epub+zip and nothing else — a trailing newline, extra whitespace, or a UTF-8 byte-order mark (BOM) is enough to trigger this.

How to fix it: Open the mimetype file in a plain-text editor, delete everything, and type application/epub+zip with no line break at the end. Save as plain ASCII/UTF-8 without a BOM, then re-zip as described under PKG-006.

OPF-003

Item '…' exists in the EPUB, but is not declared in the OPF manifest.

What it means: A warning, not an error: there’s a file inside the ZIP that the package manifest never mentions. Every resource in an EPUB is supposed to be declared as a manifest <item>. The usual culprits are leftover junk — .DS_Store, Thumbs.db, backup copies, or an image you stopped using but never deleted.

How to fix it: If the file belongs in the book, add a manifest item for it with the correct media-type. If it’s junk, delete it from the archive. Retailers generally accept files with this warning, but stray files bloat the download and occasionally confuse conversion pipelines, so clean them up.

OPF-014

The property 'remote-resources' should be declared in the OPF file.

What it means: EPUB 3 requires you to flag special behaviors on the manifest item that uses them. If a chapter loads a font or image from the web, its manifest item needs properties="remote-resources"; if it contains JavaScript, it needs properties="scripted"; MathML and inline SVG have properties too. epubcheck found the behavior in your content but not the flag in the manifest.

How to fix it: Add the named property to that file’s manifest item, e.g. <item id="ch3" href="ch3.xhtml" media-type="application/xhtml+xml" properties="scripted"/>. Multiple properties are space-separated. Better yet, ask whether you need the behavior at all — remote resources and scripts are poorly supported on e-readers, and removing them fixes the error at the root.

OPF-030

The unique-identifier '…' was not found.

What it means: The <package> element’s unique-identifier attribute points at the id of a <dc:identifier> element in the metadata — that’s how the book declares its identity (ISBN, UUID, etc.). This error means the attribute names an id that doesn’t exist, usually because the identifier element was renamed or deleted during editing.

How to fix it: Make the two ends match. If your package tag says unique-identifier="book-id", you need <dc:identifier id="book-id">urn:uuid:…</dc:identifier> in the metadata block. Any stable value works — a UUID is fine if you don’t have an ISBN.

Content errors (RSC & HTM)

These come from the XHTML content documents — invalid markup, broken internal links, and files that are referenced but missing or undeclared. RSC-005 alone accounts for a huge share of all epubcheck output.

RSC-005

Error while parsing file: <specific validation message>

What it means: The catch-all. epubcheck validates every XHTML, OPF, and nav file against the EPUB schemas, and any violation is reported as RSC-005 — so the code itself tells you almost nothing. The real diagnosis is in the message after the colon: duplicate id attributes, an element not allowed in that context, a missing required attribute, unclosed tags, and so on.

How to fix it: Ignore the code and read the trailing message plus the file, line, and column epubcheck gives you. Common examples: “Duplicate ID” means two elements share the same id — rename one. “Element X not allowed here” usually means invalid nesting, like a <div> inside a <p>. Fix each reported line; one structural mistake can cascade into several RSC-005 lines, so re-run after each fix.

HTM-004

Irregular DOCTYPE: found '…', expected '…'.

What it means: The DOCTYPE at the top of an XHTML file doesn’t match what the EPUB version expects. EPUB 3 content documents should start with the plain HTML5 doctype, while EPUB 2 used the XHTML 1.1 doctype. This typically appears after converting an old EPUB 2 book to EPUB 3, or when a tool pasted in a nonstandard DOCTYPE.

How to fix it: For EPUB 3, replace the first line of the file with <!DOCTYPE html> (after the XML declaration, if present). Do it in every content file — conversion tools tend to leave the same stale DOCTYPE everywhere.

RSC-007

Referenced resource could not be found in the EPUB.

What it means: Something in your book — an <img> src, a stylesheet link, an href — points to a file that simply isn’t in the container. Nine times out of ten it’s a path problem: wrong folder (../images/ vs images/), a renamed file, or a case mismatch (cover.JPG on disk, cover.jpg in the link — EPUB paths are case-sensitive).

How to fix it: Take the exact path from the error, and check it against the archive character by character, including capitalization and folder depth relative to the referencing file. Either fix the reference or add the missing file back into the EPUB (and declare it in the manifest).

RSC-008

Referenced resource '…' is not declared in the OPF manifest.

What it means: The mirror image of OPF-003, but an error rather than a warning: the file is present in the container and your content actually links to it, yet the OPF manifest never declares it. Since the manifest is the authoritative list of the book’s resources, an undeclared-but-used file is a spec violation.

How to fix it: Add a manifest <item> for the file with a unique id, the correct href, and the correct media-type — e.g. <item id="map1" href="images/map.png" media-type="image/png"/>.

RSC-011

Found a reference to a resource that is not a spine item.

What it means: A hyperlink points to an XHTML document that exists and is declared in the manifest, but isn’t listed in the spine — the ordered list of documents that make up the reading flow. Readers can only navigate to spine content, so the link would lead nowhere.

How to fix it: Either add the target document to the spine (an <itemref> in the OPF, with linear="no" if it shouldn’t appear in the normal page flow) or repoint the link at a document that is in the spine.

RSC-012

Fragment identifier is not defined.

What it means: A link targets an anchor that doesn’t exist: href="notes.xhtml#note-42" but nothing in notes.xhtml has id="note-42". Very common in books with footnotes, endnotes, or indexes, and after re-generating chapters (which often rewrites ids) without re-generating the links that point at them.

How to fix it: Open the target file and either add the missing id to the right element or update the link to the id that actually exists. If a conversion tool built your notes, re-export the whole book in one pass so links and anchors are generated together.

Media & CSS errors

Errors about the stuff around the text: image formats the EPUB spec doesn’t bless, and stylesheets epubcheck can’t parse.

MED-003

Non-standard image resource '…' found.

What it means: The EPUB spec defines a set of core media types every reading system must support — for images that’s JPEG, PNG, GIF, and SVG (recent spec revisions add WebP). Anything else, like a BMP or TIFF, is a “foreign resource” and may only be used if the manifest provides a fallback to a core type. epubcheck found a non-core image with no such fallback.

How to fix it: The simple fix: convert the image to JPEG or PNG and update the reference and manifest. The spec-lawyer fix — a fallback attribute chaining to a core-type item — works but is rarely worth it, since plenty of e-readers won’t render the foreign format anyway.

CSS-008

An error occurred while parsing the CSS: <details>.

What it means: epubcheck’s CSS parser hit something it couldn’t read: an unclosed brace, a stray character, malformed syntax, or occasionally a newer CSS feature it doesn’t recognize. Stylesheets exported from word processors are frequent offenders.

How to fix it: Go to the file, line, and column in the message. Check for unbalanced { } braces above that point, missing semicolons, and smart quotes that crept in from a document editor. Running the stylesheet through a CSS linter or the W3C CSS validator usually pinpoints the exact character. If a genuinely valid modern property trips an older epubcheck, update epubcheck before contorting your CSS.

Navigation errors (NCX)

EPUB 3 books often carry a legacy toc.ncx file alongside the modern nav document, for compatibility with older readers. It has to agree with the rest of the package.

NCX-001

NCX identifier ('…') does not match OPF identifier ('…').

What it means: The toc.ncx file carries its own copy of the book’s unique identifier, in a <meta name="dtb:uid"> element in its head. epubcheck compares it with the <dc:identifier> in the OPF, and they don’t match. This usually happens when the identifier is changed in one file but not the other — for example, adding an ISBN in the OPF while the NCX still holds an old UUID.

How to fix it: Copy the exact value of the OPF’s <dc:identifier> into the NCX: <meta name="dtb:uid" content="urn:isbn:…"/>. Character-for-character — prefixes like urn:uuid: count.

Or never see an epubcheck error again.

publish.ai runs epubcheck on every EPUB before it’s delivered — your KDP launch package ships with a validated EPUB, print-ready interior and cover PDFs, Amazon listing copy, and launch graphics. One upload, minutes, from $29.99.

Publish my book →Browse a real sample package

Common questions

What is RSC-005 in epubcheck and how do I fix it?＋

RSC-005 is epubcheck’s catch-all for schema validation failures in XHTML, OPF, and nav files. The code itself is generic — the actual problem is described in the message after “Error while parsing file:”, along with a file name, line, and column. Read that message: duplicate ids, elements in invalid positions, and missing required attributes are the most common causes, and each is fixed at the exact line reported.

How do I fix RSC-007 (referenced resource could not be found)?＋

Something in your book links to a file that isn’t in the EPUB container. Check the path in the error against the archive character by character: folder depth, spelling, and capitalization (EPUB paths are case-sensitive, so cover.JPG and cover.jpg are different files). Fix the reference or restore the missing file and declare it in the manifest.

What does OPF-014 mean?＋

EPUB 3 requires special behaviors to be flagged on the manifest item that uses them: files loading web resources need properties="remote-resources", files containing JavaScript need properties="scripted", and so on. OPF-014 means epubcheck found the behavior in the content but not the property in the manifest. Add the named property to that item — or remove the remote resource or script, which e-readers support poorly anyway.

How do I fix PKG-006 (mimetype missing or not first)?＋

An EPUB’s ZIP archive must start with an uncompressed file named mimetype containing exactly application/epub+zip. Re-zipping an edited EPUB with a normal ZIP tool breaks this. Rebuild with the mimetype entry first and stored uncompressed — zip -X0 book.epub mimetype, then zip -rg book.epub META-INF OEBPS — or edit in a tool like Sigil that repacks correctly.

How do I fix RSC-012 (fragment identifier is not defined)?＋

A link points to an anchor that doesn’t exist — for example href="notes.xhtml#note-42" when no element in notes.xhtml has id="note-42". Add the missing id to the target element or correct the link. If your footnotes were generated by a conversion tool, re-export the whole book in one pass so anchors and links stay in sync.

Will Amazon KDP reject my EPUB for epubcheck warnings?＋

In practice, epubcheck ERRORs and FATALs are what get files rejected or badly converted; WARNINGs (like OPF-003 for undeclared extra files) usually pass. KDP doesn’t publish an exact mapping to epubcheck codes, though, so the safe policy is simple: fix every error, and clean up warnings too — a zero-issue file removes the guesswork.