Use EpubBit
Professional EPUB tools for indie authors worldwide.
EpubBit guides/Validation
Validation

How to Read and Fix EPUBCheck Errors Before Submitting Your Ebook

EPUBCheck errors can block your ebook submission. Learn to read error codes, fix common issues, and validate your EPUB like a pro before uploading to retailers.

12 min read · EpubBit Editorial Team

You've finished writing, editing, and formatting your ebook. You export it as an EPUB, upload it to your chosen retailer, and wait. Then the rejection email arrives: “EPUBCheck failed.” You open the error log and see a wall of cryptic codes and file paths. What do they mean? How do you fix them?

EPUBCheck is the official validation tool for EPUB files, maintained by the W3C. Retailers like Amazon KDP, Apple Books, and Kobo often run it (or a similar validator) before accepting your book. Passing EPUBCheck doesn't guarantee a perfect reading experience, but failing it almost always means your book won't be distributed. This guide walks you through reading EPUBCheck output, fixing the most common errors, and building a validation workflow that saves you time and frustration.

What EPUBCheck Actually Checks

EPUBCheck verifies that your EPUB conforms to the EPUB specification. It checks three main areas:

  • Package document (OPF): Metadata, manifest, spine, and guide elements must be correctly structured.
  • Content documents (XHTML): Markup must be well-formed and valid, with proper nesting and closed tags.
  • Resources: All referenced files (images, CSS, fonts) must exist, be declared in the manifest, and use correct media types.

It also checks for accessibility metadata, navigation documents, and EPUB 3-specific features. The tool outputs errors (which must be fixed), warnings (which should be reviewed), and infos (which are often ignorable).

How to Run EPUBCheck and Read the Output

You can run EPUBCheck as a command-line tool, a Java application, or through a graphical interface. Many authoring tools integrate it. If you prefer a GUI, EpubBit includes a built-in validator that runs EPUBCheck and presents results in a readable list, but you can also use the official standalone version.

When you run EPUBCheck, you'll see output like this:

ERROR(OPF-031): The file "OEBPS/chapter1.xhtml" is not declared in the manifest.
WARNING(CSS-007): The CSS selector ".title" is not used.
INFO(HTM-014): The lang attribute is missing on the html element.

Each line has a severity, a code in parentheses, a message, and often a file path and line number. The code is your key to understanding and fixing the issue. Codes are grouped by prefix: OPF for package document, HTM for HTML/XHTML, CSS for stylesheets, RSC for resources, and so on.

Step 1: Fix Errors First, Then Warnings

Errors are fatal: they prevent the EPUB from being valid. Warnings indicate potential problems but don't block validation. Info messages are often style suggestions. Always fix all errors before submitting. Warnings should be reviewed; some may indicate real issues (like missing alt text), while others are harmless.

Step 2: Locate the Problem in Your Source Files

EPUBCheck reports file paths relative to the EPUB's root. For example, OEBPS/chapter1.xhtml means the file chapter1.xhtml inside the OEBPS folder. If you're working with an unzipped EPUB, you can open that file in a text editor. If you're using an authoring tool, you may need to export or unpack the EPUB to edit the source.

Common EPUBCheck Errors and How to Fix Them

OPF-031: File Not Declared in the Manifest

What it means: A file referenced in your content (e.g., an image or a chapter) is not listed in the OPF manifest. Every resource in the EPUB must be declared.

How to fix: Open the OPF file (usually content.opf or package.opf). Find the <manifest> section. Add a new <item> element for the missing file. For example:

<item id="chapter1" href="chapter1.xhtml" media-type="application/xhtml+xml"/>

Make sure the href matches the file's path relative to the OPF, and the media-type is correct. For images, use image/jpeg, image/png, etc. For CSS, use text/css.

OPF-003: Duplicate ID in Manifest

What it means: Two or more items in the manifest share the same id attribute. IDs must be unique.

How to fix: Search the manifest for duplicate id values. Rename one of them. IDs are arbitrary strings, so you can use chapter1, chapter1b, etc. Ensure any references to that ID (e.g., in the spine) are updated.

HTM-004: Element Not Allowed as Child of ...

What it means: Your XHTML has invalid nesting. For example, a <div> directly inside a <ul> without an <li> parent, or a <p> inside a <span>.

How to fix: Review the reported line and its surrounding markup. Ensure elements follow HTML5 content models. Common fixes include wrapping text in appropriate block elements, closing tags properly, and avoiding inline elements containing block elements.

RSC-005: File Not Found

What it means: A referenced file (e.g., an image in <img src="...">) does not exist at the specified path.

How to fix: Check the file path in your XHTML or CSS. Paths are case-sensitive and relative to the file containing the reference. If your image is in Images/cover.jpg and your chapter is in OEBPS/, the correct relative path is ../Images/cover.jpg. Verify the file exists and the name matches exactly.

CSS-008: CSS Syntax Error

What it means: Your CSS has a syntax error, such as a missing semicolon, unclosed brace, or invalid property value.

How to fix: Open the CSS file and look at the reported line. Common issues include missing semicolons at the end of declarations, using unsupported properties, or typos in property names. Use a CSS linter or your editor's syntax highlighting to spot errors.

HTM-014: Missing Language Attribute

What it means: The <html> element lacks a lang attribute. This is important for accessibility and text-to-speech.

How to fix: Add lang="en" (or the appropriate language code) to the <html> tag in each XHTML file. For example: <html xmlns="http://www.w3.org/1999/xhtml" lang="en">.

OPF-030: Spine Item Not Found

What it means: An item referenced in the <spine> does not exist in the manifest.

How to fix: Check the idref in the spine. It must match an id in the manifest. If you renamed or removed a chapter, update the spine accordingly.

Step-by-Step Validation Workflow

Follow this workflow to catch and fix errors efficiently:

  1. Export a draft EPUB from your writing tool or editor.
  2. Run EPUBCheck using the command line or a GUI tool. Save the output to a text file for reference.
  3. Count errors and warnings. If you have more than 20 errors, fix the most frequent ones first—they often share a root cause.
  4. Fix errors in your source files. If you're working with an unzipped EPUB, edit the XHTML, CSS, or OPF directly. Then re-zip the EPUB (ensuring mimetype is the first file and uncompressed).
  5. Re-run EPUBCheck after each round of fixes. Repeat until no errors remain.
  6. Review warnings. Decide which to fix based on impact. For example, missing alt text (warning) should be fixed for accessibility; unused CSS selectors can be ignored.
  7. Test in reading systems. Open your EPUB in multiple apps (Apple Books, Calibre, Adobe Digital Editions) to catch rendering issues that EPUBCheck doesn't detect.

If you use EpubBit, its validation panel can run EPUBCheck and group errors by type, making it easier to tackle them. It also offers one-click fixes for some common issues, like adding missing manifest items.

Beyond EPUBCheck: Retailer-Specific Requirements

Passing EPUBCheck is necessary but not sufficient. Retailers may have additional requirements. For example, Amazon KDP has specific guidelines for cover size, file size, and metadata. Apple Books requires a valid ISBN and may enforce stricter accessibility standards. Always check the current official documentation for each retailer you plan to use. Requirements change, so verify before submitting.

Preventing Errors Before They Happen

The best way to deal with EPUBCheck errors is to avoid them. Here are practical tips:

  • Use a dedicated EPUB editor that validates as you work. EpubBit, Sigil, and Calibre's editor all offer validation features.
  • Keep your source files clean. Avoid pasting from Word directly into HTML; use a plain-text editor or a tool that sanitizes markup.
  • Declare all resources. When you add an image or font, immediately add it to the manifest.
  • Use consistent naming. Avoid spaces and special characters in filenames. Stick to lowercase letters, numbers, and hyphens.
  • Validate early and often. Run EPUBCheck after major edits, not just at the end.

Conclusion

EPUBCheck errors can seem daunting, but they're usually straightforward to fix once you understand the codes. By reading the output carefully, fixing errors systematically, and validating early, you'll ensure your EPUB meets industry standards and sails through retailer submissions. Remember that validation is a step in your workflow, not a one-time event. With practice, you'll internalize the common patterns and spend less time debugging and more time writing.