EPUB errors and how to fix them.

PKG-006: Mimetype file entry is missing or is not the first file in the archive.

An EPUB is a ZIP archive whose very first entry must be a file named mimetype. Reading systems look at the first bytes of the archive to recognise an EPUB, so a mimetype file in any other position is as good as missing.

Why it happens

• The EPUB was unzipped, edited and zipped again with a regular archive tool, which orders files alphabetically or by folder.
• A script built the archive and added META-INF or OEBPS before mimetype.
• The mimetype file was deleted while editing the unpacked book.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. The exported file is written correctly, so this error does not come back. Run EPUBCheck again to confirm.

Fix it by hand

The ZIP archive itself. Re-create it with mimetype added first and stored without compression, then the rest.

zip -r book.epub .

zip -X0 book.epub mimetype
zip -rDX9 book.epub META-INF OEBPS

Folder names after mimetype depend on the book; OEBPS is the most common.

PKG-007: Mimetype file should only contain the string "application/epub+zip" and should not be compressed.

The mimetype file has the wrong text, extra characters such as a line break, or was compressed. It must hold exactly application/epub+zip, stored as is, so reading systems can recognise the archive without unpacking it.

Why it happens

• A text editor added a line break or a byte order mark when the file was saved.
• The archive tool compressed every file, mimetype included.
• The file was written by hand with a different media type.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. The exported file is written correctly, so this error does not come back. Run EPUBCheck again to confirm.

Fix it by hand

The mimetype file at the root of the archive.

application/epub+zip\n   (with a trailing line break, compressed)

application/epub+zip   (no line break, stored uncompressed)

Write it with printf rather than echo, which adds a line break: printf 'application/epub+zip' > mimetype

RSC-008: Referenced resource "…" is not declared in the OPF manifest.

A chapter uses a file, usually an image, font or stylesheet, that is in the archive but missing from the manifest in the package document. Every file a book uses must be listed there with its media type.

Why it happens

• An image was added to the unpacked book without a matching manifest item.
• A file was renamed and the manifest still lists the old name.
• A conversion tool copied assets but did not update the package document.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. Export gives each image a fresh name, updates every reference to it and lists it in the manifest.

Fix it by hand

The manifest element of the package document (the .opf file).

<manifest>
  <item id="c2" href="chapter-2.xhtml" media-type="application/xhtml+xml"/>
</manifest>

<manifest>
  <item id="c2" href="chapter-2.xhtml" media-type="application/xhtml+xml"/>
  <item id="dot" href="dot.png" media-type="image/png"/>
</manifest>

OPF-014: The property "…" should be declared in the OPF file.

A chapter contains something EPUB 3 asks the manifest to announce, such as inline SVG, MathML, scripts or a resource on the web, and its manifest item has no properties attribute saying so. Reading systems use these properties to decide how to render the chapter.

Why it happens

• SVG or MathML was pasted into a chapter after the package was written.
• The book was upgraded from EPUB 2, which had no such properties.
• A chapter links to an image or font on a website, which needs "remote-resources".

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. Export works out each chapter's properties from its content. If the property was remote-resources, also see RSC-006: the remote file itself is the real problem.

Fix it by hand

The chapter's item in the manifest of the .opf file.

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

<item id="c1" href="chapter-1.xhtml" media-type="application/xhtml+xml" properties="svg"/>

Use a space-separated list when several apply, for example properties="svg mathml".

OPF-015: The property "…" should not be declared in the OPF file.

The manifest says a chapter contains SVG, MathML or scripts, but it does not. A stale property can make a reading system prepare for content that is not there.

Why it happens

• An illustration or formula was removed and the manifest kept its property.
• A tool or template marked every chapter the same way.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. The exported file is written correctly, so this error does not come back. Run EPUBCheck again to confirm.

Fix it by hand

The chapter's item in the manifest of the .opf file.

<item id="c1" href="chapter-1.xhtml" media-type="application/xhtml+xml" properties="svg"/>

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

NCX-001: NCX identifier ("…") does not match OPF identifier ("…").

The book still carries an EPUB 2 table of contents (toc.ncx) whose dtb:uid is not the book's identifier. The NCX is optional in EPUB 3, but when present the two must match.

Why it happens

• The identifier was changed in the package document, for example to an ISBN, and the NCX kept the old one.
• Chapters or a table of contents were copied in from another book.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. Export writes an EPUB 3 navigation document from your table of contents and no NCX, so there is nothing left to mismatch.

Fix it by hand

The meta name="dtb:uid" element in toc.ncx, matched to dc:identifier in the .opf file.

<meta name="dtb:uid" content="urn:uuid:00000000-0000-4000-8000-000000000000"/>

<meta name="dtb:uid" content="urn:uuid:8b6f3c2e-5f4a-4d1b-9a7e-2c3d4e5f6a7b"/>

RSC-005: Error while parsing file: package dcterms:modified meta element must occur exactly once

EPUB 3 requires exactly one last-modified date in the package metadata, so reading systems and stores can tell two versions of the same book apart. It is missing, or there is more than one.

Why it happens

• The book was written as EPUB 2 and its version number raised to 3.0 by hand.
• Two tools each added their own date.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. Export writes one dcterms:modified with the time of the export.

Fix it by hand

The metadata element of the .opf file.

<meta property="dcterms:modified">2026-11-13T00:00:00Z</meta>

Use UTC in this exact form, with no fractions of a second.

RSC-005: Error while parsing file: element "center" not allowed here

A chapter uses an HTML element that EPUB 3's XHTML does not allow. center and font are the usual ones: old presentational tags that a style should do instead.

Why it happens

• Text was pasted from an old web page or a word processor's HTML export.
• The book was converted by a tool that writes HTML 4.

Fix it in E-BOOKA

Open the book on the EPUB checker. center and font are removed as it loads and their text is kept; the repair list shows what changed. Centre text again in the editor if you need to, then export.

Fix it by hand

The chapter file named in the error, at the line and column EPUBCheck gives.

<center><font color="red">Opening line.</font></center>

<p class="centered">Opening line.</p>
/* in the stylesheet */
.centered { text-align: center; }

RSC-005: Error while parsing file: element "ol" incomplete; missing required element "li"

The table of contents in the navigation document is an empty list. EPUB 3 needs at least one entry, and Amazon KDP and Apple Books both expect a working table of contents.

Why it happens

• A tool wrote the navigation document before any chapters existed.
• Every entry was deleted while editing the table of contents by hand.

Fix it in E-BOOKA

Open the book on the EPUB checker. A missing or empty table of contents is rebuilt from the book's chapters as it loads. Review the entries in the editor, then export.

Fix it by hand

The nav epub:type="toc" element in the navigation document (often nav.xhtml).

<nav epub:type="toc"><ol></ol></nav>

<nav epub:type="toc"><ol>
  <li><a href="chapter-1.xhtml">One</a></li>
</ol></nav>

RSC-016: Fatal Error while parsing file: The entity "nbsp" was referenced, but not declared.

A chapter uses an HTML named entity such as   or —. EPUB chapters are XML, which only knows five named entities, so the chapter cannot be read at all. That is why this one is fatal.

Why it happens

• Text was pasted from a web page or written in an HTML editor.
• A conversion tool wrote HTML entities into XHTML.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. Export writes every named entity as the character itself, so a non-breaking space stays a non-breaking space.

Fix it by hand

The chapter file and line EPUBCheck names.

<p>Opening&nbsp;line&mdash;here.</p>

<p>Opening&#160;line&#8212;here.</p>

Numeric references like   or the characters themselves are both valid. Only & < > " and ' may stay named.

HTM-004: Irregular DOCTYPE: found "…", expected "<!DOCTYPE html>".

A chapter declares an XHTML 1.1 or another old doctype. EPUB 3 chapters use the HTML5 doctype only. XML tools that see the old doctype may also try to fetch its DTD from the web, which fails offline.

Why it happens

• The chapters come from an EPUB 2 book.
• A template or converter still writes the XHTML 1.1 doctype.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again from the editor. The exported file is written correctly, so this error does not come back. Run EPUBCheck again to confirm.

Fix it by hand

The second line of each chapter file named in the error.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<!DOCTYPE html>

RSC-007: Referenced resource "…" could not be found in the EPUB.

A link or image points to a file that is not in the book. Readers who follow the link reach nothing, and a missing image leaves a gap.

Why it happens

• A chapter was renamed, split or deleted and links to it were not updated.
• Links were copied from another book or from the manuscript's own file names.
• An image was removed while its img tag stayed.

Fix it in E-BOOKA

Open the book on the EPUB checker. The Publisher view lists each broken link with Go to link, so you can point it at the right chapter or remove it. Sign in with a free account to see each finding and jump to it. Fix it, export, and run EPUBCheck again.

Fix it by hand

The chapter EPUBCheck names. Search it for the missing file name.

<a href="missing.xhtml">Lost</a>

<a href="chapter-2.xhtml">Lost</a>

RSC-012: Fragment identifier is not defined.

A link points to a place inside a chapter, the part after #, and no element in that chapter has that id. The chapter opens, but not at the intended place.

Why it happens

• A heading or note was deleted, or its id changed, while links to it stayed.
• Footnote links were written by hand with a typo.
• A converter wrote ids for headings in one pass and links in another.

Fix it in E-BOOKA

Open the book on the EPUB checker. The Publisher view lists each link to a missing anchor with Go to link. Sign in with a free account to see each finding and jump to it. Fix it, export, and run EPUBCheck again.

Fix it by hand

The link in the chapter EPUBCheck names, and the target chapter.

<a href="chapter-2.xhtml#nowhere">Go on</a>
<!-- chapter-2.xhtml --> <p id="end">

<a href="chapter-2.xhtml#end">Go on</a>

RSC-006: Remote resource reference is not allowed in this context; resource "…" must be located in the EPUB container.

A chapter loads an image, font or other file from a website instead of from inside the book. Most reading systems work offline and will not fetch it, and stores reject it.

Why it happens

• Images were pasted from a web page and kept their web addresses.
• A stylesheet loads a web font from a font service.

Fix it in E-BOOKA

Open the book on the EPUB checker. The Publisher view lists each remote file. Download the image and insert it into the chapter from the editor so it travels inside the book. Sign in with a free account to see each finding and jump to it. Fix it, export, and run EPUBCheck again.

Fix it by hand

The chapter or stylesheet named in the error.

<img src="https://example.com/remote.png" alt="Map"/>

<img src="images/map.png" alt="Map"/>
<!-- plus a manifest item for images/map.png -->

Links a reader clicks (a href) may point to websites; only files the book loads must be inside it.

image-alt: Ensure <img> elements have alternative text or a role of none or presentation

An image has no alt attribute, so a screen reader can only say that an image is there, or reads out its file name. Informative images need a short description; decorative ones need an empty alt.

Why it happens

• Images were inserted without a description, which most word processors allow.
• A converter dropped the descriptions the manuscript had.

Fix it in E-BOOKA

Open the book on the EPUB checker. The Publisher view lists each image without a description with Go to image, where you can write one. Only you can judge what the image shows. Sign in with a free account to see each finding and jump to it. Fix it, export, and run EPUBCheck again.

Fix it by hand

The img element Ace points to.

<img src="images/map.png"/>

<img src="images/map.png" alt="Map of the river delta with the three villages marked"/>
<img src="images/flourish.png" alt=""/>   <!-- decorative -->

alt="image1" or the file name is not a description. Ace cannot tell; Apple Books guidance asks for useful ones.

heading-order: Ensure the order of headings is semantically correct

Headings skip a level, for example from h1 straight to h3. Screen reader users move through a book by headings, and a skipped level suggests a missing section.

Why it happens

• A heading level was picked for its size rather than its place in the outline.
• A section between two headings was deleted.

Fix it in E-BOOKA

Open the book on the EPUB checker. The Publisher view lists each jump with Go to heading. Change the level, or add the heading that is missing. Sign in with a free account to see each finding and jump to it. Fix it, export, and run EPUBCheck again.

Fix it by hand

The heading Ace points to and the one before it.

<h1>One</h1>
<h3>Too deep</h3>

<h1>One</h1>
<h2>Too deep</h2>

Change the size with a style, not by choosing a different heading level.

epub-type-has-matching-role: Ensure the element has an ARIA role matching its epub:type

An element is marked with epub:type, for example a chapter, footnote or the table of contents, but has no matching ARIA role. Reading systems use epub:type; screen readers only understand the role.

Why it happens

• The book was made for EPUB 3.0, before the matching roles were recommended.
• A template adds epub:type everywhere and roles nowhere.

Fix it in E-BOOKA

Open the book on the EPUB checker. The matching roles are added as it loads, for example role="doc-chapter" beside epub:type="chapter" and role="doc-toc" on the table of contents. Then export.

Fix it by hand

The element Ace points to.

<section epub:type="chapter">
<nav epub:type="toc">

<section epub:type="chapter" role="doc-chapter">
<nav epub:type="toc" role="doc-toc">

aria-roles: Ensure all elements with a role attribute use a valid value

An element has a role that no ARIA or DPUB-ARIA specification defines. Assistive technology cannot interpret it, and an invalid role can hide the element's real meaning. EPUBCheck reports the same markup as RSC-005.

Why it happens

• A role was invented or misspelled, such as role="chapterish" or role="doc-chaptr".
• epub:type values were copied into role, where most of them are not valid.

Fix it in E-BOOKA

Open the book on the EPUB checker. Roles no reading system recognises are removed as it loads, and a valid role is added where the element's epub:type implies one. Then export.

Fix it by hand

The element Ace points to.

<section role="chapterish">

<section role="doc-chapter">

html-has-lang: Ensure every HTML document has a lang attribute

Also reported as epub-lang

A chapter (html-has-lang) or the package document (epub-lang) does not say which language it is in. Screen readers pick their voice and pronunciation from it, so the book may be read with the wrong accent.

Why it happens

• The language was set in the book's metadata but not on each chapter.
• Chapters were written by a tool that leaves out lang and xml:lang.

Fix it in E-BOOKA

Open the book on the EPUB checker, check the language on the editor's Metadata tab, and download the book again. Export writes that language on every chapter and on the package document.

Fix it by hand

The html element of each chapter, and the package element of the .opf file.

<html xmlns="http://www.w3.org/1999/xhtml">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

metadata-accessmode: Ensures a 'schema:accessMode' metadata is present

Also reported as metadata-accessibilityhazard, metadata-accessibilitysummary, metadata-accessibilityfeature, metadata-accessmodesufficient

The package document does not describe the book's accessibility: how it can be read (accessMode, accessModeSufficient), what helps (accessibilityFeature), what could harm (accessibilityHazard) and a summary. Stores and libraries show this to readers before they buy, and the European Accessibility Act asks for it on e-books sold in the EU.

Why it happens

• The book was made before accessibility metadata was common.
• The authoring tool has no fields for it.

Fix it in E-BOOKA

Open the book on the EPUB checker and download it again: export writes accessMode, accessibilityHazard and accessibilitySummary from what it finds in the book. accessibilityFeature and accessModeSufficient are statements only you can make after reviewing the book: declare them on the editor's Metadata tab with the Publisher plan.

Fix it by hand

The metadata element of the .opf file.

<meta property="schema:accessMode">textual</meta>
<meta property="schema:accessModeSufficient">textual</meta>
<meta property="schema:accessibilityFeature">structuralNavigation</meta>
<meta property="schema:accessibilityHazard">none</meta>
<meta property="schema:accessibilitySummary">Headings and a table of contents give structure.</meta>

Declare only what is true of the book after review. An Ace report is not a certificate of compliance.

Internal cover is missing or too small (Amazon KDP, Apple Books)

A valid EPUB does not need a cover, but stores do. Amazon KDP asks for a cover image inside the book, separate from the marketing cover uploaded in title setup, at least 1,200 px on its longest side. Apple Books expects an interior cover too.

Why it happens

• The cover was only uploaded to the store dashboard, not built into the EPUB.
• A small thumbnail was used as the interior cover.
• The cover image is in the book but not marked as the cover in the manifest.

Fix it in E-BOOKA

Open the book in the EPUB cover changer and add or replace the cover; it sizes the image for the store or reader you choose and marks it as the cover. Export, then check it again in the store's own previewer.

Fix it by hand

The cover image's item in the manifest of the .opf file.

<item id="cover-image" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>

Amazon KDP guidance read 2026-10-28; Apple Books asset guide read 2026-08-26. Store requirements change, and passing these checks is not the store accepting the book.