Technology · PRACTICAL GUIDE
EPUB raises “no item named”? Trace the missing ZIP member before changing the book
A missing script, a missing chapter and a case mismatch can produce the same KeyError. Four controlled packages show why a clean ZIP test is not an EPUB completeness check.
An EPUB error saying there is no item named a particular path means an archive lookup failed. It does not tell you whether the missing target is a chapter, a script or an incorrectly spelled reference. Preserve the exact file and error path before changing anything.
We tested four original local EPUB 3 packages with Python 3.12.14, EbookLib 0.20.0 and lxml 6.1.3. The control loaded. Removing a declared script, removing the second spine chapter, or changing a chapter reference's capital letter each produced KeyError. All four archives passed ZipFile.testzip(), and their saved input hashes stayed unchanged during the audit.
This is a package-lookup test, not proof that the control is fully EPUB-conformant or that a device will display any of these files correctly. We did not run EPUBCheck, Calibre, EpubSplit or a graphical reader. The practical addition is a comparison that routes the same exception to different investigations.
Follow the reference from the package to the archive
List the archive members without extracting or overwriting them; Python's command-line option is python -m zipfile -l book.epub. Read META-INF/container.xml to identify the package document. In our cases it was OEBPS/package.opf, so a manifest href of Text/chapter2.xhtml referred to OEBPS/Text/chapter2.xhtml.
Record the manifest ID, original href, media type, resolved member name, exact existence and any spine position. W3C defines the package document as the base for its URLs, and container names are case-sensitive. Our tests used simple local paths; remote resources, encoded names, fragments, multiple renditions or malformed XML need their applicable URL and package rules, not a guessed filesystem join.
Separate missing content from a reference mismatch
In the missing-chapter case, c2 pointed to the absent OEBPS/Text/chapter2.xhtml at spine position 2. Do not substitute an empty chapter, skip the exception and label the result complete. Obtain a corrected source file or have the authorized producer restore the actual content and its links.
In the case-mismatch case, the manifest requested Text/Chapter1.xhtml while the archive contained Text/chapter1.xhtml. The audit reported the differently cased candidate, without automatically selecting or renaming it. Check all references and the producer's intended file before a targeted correction; a near match is a clue, not proof of equivalence.
A script outside the spine is not automatically disposable
Removing OEBPS/js/unused.js also stopped EbookLib, although both spine chapters remained in the archive. In this synthetic case we knew the script was unused because we created every file. A script outside the spine in someone else's book can still be referenced by content or support a feature.
Trace dependencies and ask the producer to restore the asset or deliberately remove an obsolete declaration and its references. Do not classify a missing local file as an allowed remote resource, download a similarly named script, or catch every KeyError and continue. Upstream issue 281 already describes this kind of manifest-loading failure; it is not a newly discovered mechanism.
Keep ZIP, publication and delivery checks distinct
testzip() checks stored members' CRCs and headers; it does not know which members the publication intended to contain. In our four cases it returned None every time, including the missing chapter. Loading the control with EbookLib established only that this parser accepted it under the tested options, not complete EPUB conformance.
Calibre's documented Tools → Check book already reports broken links and OPF problems, and W3C recommends a conformance checker such as EPUBCheck. Use those existing routes on a working copy and retain their reports. After an authorized repair, rerun the originally failing operation, verify the intended chapter order and text, and test the required reading workflow. Preserve the original and record any unresolved resource; a green retry alone does not prove that no text or functionality was lost.
