What this error means
EPUBCheck is the open-source validator maintained by the W3C and IDPF that confirms an EPUB file conforms to the spec. KDP runs it on every Kindle upload. If EPUBCheck reports errors (not just warnings), the file is rejected with "Your EPUB file did not pass validation."
The error report lists each issue with file, line number, and severity (FATAL, ERROR, WARNING). Only FATAL and ERROR cause rejection; WARNINGs are allowed.
Common errors:
- Missing required metadata (title, creator, language, identifier)
- Malformed XHTML (unclosed tags, invalid attributes)
- Broken references in the OPF manifest
- Files referenced but not included in the package
- Files included but not declared in the manifest
- Unsupported MIME types (e.g. TIFF images, which Kindle rejects)
- Encoding issues (non-UTF-8 XHTML)
Why it happens
Hand-edited EPUBs from Sigil or Calibre with malformed HTML are the top cause. Authors edit raw XHTML to tweak something and break the syntax.
Exporting from Word as EPUB via plugins (third-party converters) often produces invalid markup — orphaned <span> tags, missing alt text, broken table structure.
Calibre's conversion engine can produce technically valid but slightly off EPUBs depending on input. Word .docx → EPUB conversion is the most error-prone path.
Renaming files inside the EPUB without updating the OPF manifest. The manifest is an XML inventory of every file; rename one and the reference breaks.
Mixing EPUB 2 and EPUB 3 metadata — Atticus and some online converters output a hybrid that EPUBCheck flags.
Missing language declaration in the OPF (<dc:language>en-GB</dc:language>). Surprisingly common because some tools omit it.
Image format mismatch — referencing a .tif file in HTML but KDP requires JPEG/PNG/GIF/BMP only.
The fix
Step 1: Run EPUBCheck locally. Download the latest from github.com/w3c/epubcheck — it's free and open source. You need Java installed.
Step 2: From a terminal, run:
java -jar epubcheck.jar your-book.epub
Step 3: Read the output. Each error has the form:
ERROR(RSC-007): your-book.epub/OEBPS/content.opf(4,42): Referenced resource missing in the package.
Translation: line 4, column 42 of content.opf refers to a file that isn't in the EPUB.
Step 4: Open the EPUB with Sigil (sigil-ebook.com, free). Sigil treats the EPUB as a project with all files visible — XHTML, CSS, OPF, NCX, images.
Step 5: Fix each error in order:
- "Referenced resource missing" → add the missing file to the manifest or remove the reference
- "Missing required metadata" → open content.opf and add the missing dc:title / dc:creator / dc:language / dc:identifier entries
- "Element name does not match" → close the unclosed tag in the XHTML file at the reported line
- "Image format not allowed" → convert TIFF/WebP images to JPG, replace, update references
- "Encoding not UTF-8" → in Sigil, right-click the file → Encoding → UTF-8 without BOM
Step 6 (Atticus / Vellum users): Both export valid EPUB 3 in most cases. If you're failing, regenerate the EPUB rather than hand-editing — the export is usually fine but a previous manual edit broke it.
Step 7 (Calibre users): Calibre → Edit Book → Tools → Check Book runs an internal validator. Fix the issues it lists. Re-save.
Step 8: Re-run EPUBCheck. Repeat until you see "No errors or warnings detected" or only warnings.
Step 9: Upload to KDP. Their preview tool will render the corrected EPUB on Kindle Fire, Paperwhite, and phone.
How to pre-flight it
Our free KDP Readiness Score runs EPUBCheck on your file, parses the output, and shows each error with file, line, and a plain-English fix suggestion. We also check the 30+ other KDP rules including image format, cover dimensions, and metadata.
Related errors
- KDP error: TOC links broken
- KDP error: right-to-left flag missing in OPF
- KDP error: fixed-layout metadata missing
FAQ
Are warnings as bad as errors? No — EPUBCheck warnings don't trigger KDP rejection. Only FATAL and ERROR do. Warnings are best-practice suggestions.
Can I upload my .docx instead? Yes — KDP accepts .docx and converts it internally. But you have less control over the result. EPUB is preferred for serious authors.
What about KPF or KFX format? KDP accepts EPUB and converts to KFX server-side. You don't need to generate KFX yourself unless you use Kindle Create.
My EPUB passes locally but fails on KDP — why? KDP runs a stricter EPUBCheck plus their own additional checks (cover dimensions, image format, file size). Cross-check against their full guidelines, not just EPUBCheck.
