This error means a spine entry points to an ID that the manifest does not define. In an EPUB package file (the OPF), the <spine> lists the reading order, and each <itemref> must name an item from the <manifest> by its id, not by its file name. The fix is almost always to correct the idref to match an existing manifest id, or to add the missing manifest item, then re-validate the exported file.
What does the EPUB spec actually require?
The EPUB 3.3 specification says each itemref must reference the ID of an item in the manifest through its idref attribute, that an item ID must not be referenced more than once, and that every referenced item must be an EPUB content document (or a foreign document with a fallback chain that includes one). It also says the navigation document does not have to appear in the spine (W3C: EPUB 3.3, section 5.7.2). Those rules explain the four most common causes of this error:
- A typo or a case difference, such as
Chapter-1againstchapter-1. - A chapter that was renamed or deleted from the manifest but not from the spine.
- A spine entry that uses the file path instead of the ID.
- An export tool that regenerated IDs while an older spine was kept.
How do you find the broken reference?
Unzip a copy of the EPUB. Open META-INF/container.xml and read the full-path attribute of the rootfile element. That path points to the OPF file. Run EPUBCheck first and note the file, line and column in its report (EPUBCheck, W3C), then jump to that line in the OPF.
What does a mismatch look like?
<manifest>
<item id="chapter-one" href="xhtml/chapter01.xhtml"
media-type="application/xhtml+xml"/>
</manifest>
<spine>
<itemref idref="chapter-1"/>
</spine>
The manifest defines chapter-one, but the spine asks for chapter-1. The file name chapter01.xhtml is irrelevant to the match. Change only the idref:
<spine>
<itemref idref="chapter-one"/>
</spine>
Which fix applies to which cause?
| Symptom | Likely cause | Fix |
|---|---|---|
| idref differs by case or a dash | Typo or hand edit | Copy the manifest id into the idref |
| idref names an item that is not in the manifest | Chapter deleted or not added | Add a manifest item or remove the itemref |
| idref contains a path or extension | File name used instead of id | Use the manifest id |
| Error returns after every export | Tool rewrites IDs or reuses an old OPF | Fix the source project or export setting |
| Same id listed twice in the spine | Copy and paste | Keep one itemref per item |
How do you fix it without changing the reading order?
- Back up the EPUB and edit a copy.
- Correct each bad
idrefin place so the position of everyitemrefstays the same. - If a chapter should exist, add a manifest
itemwith a unique id, the righthrefand the media typeapplication/xhtml+xml. - If a chapter was removed, delete its orphaned
itemref. - Check that no manifest ID repeats and that every
hrefpoints to a file that exists.
Be careful with the mimetype file when repackaging by hand. The EPUB spec reserves that name for the container and says the mimetype file and the files in META-INF must not be listed in the manifest. Most ZIP tools need a special setting to store mimetype first and uncompressed, which is why repackaging with the same exporter is usually safer than zipping by hand.
How do you validate after the fix?
Run EPUBCheck on the final exported file, not on your working folder. A typical command is:
java -jar epubcheck.jar repaired.epub
A clean structure does not prove that the book reads well. EPUBCheck checks the technical package; it does not know whether chapter three should come before chapter two. Open the file in at least two reading apps and page through the table of contents and the first and last chapters. If you also need discoverability and accessibility data, the next step is the metadata, which we cover in our EPUB accessibility metadata guide, and the review checklist in automated vs manual accessibility checks.
How can you prevent it?
- Use stable IDs that do not contain spaces or symbols, and never edit them by hand in several places.
- Keep one source project and regenerate the EPUB from it rather than patching old exports.
- Use
linear="no"only for auxiliary material such as notes or answer keys, as the spec describes, not for normal chapters. - Run validation on every release, not only the first.
Where does the writing workflow fit?
Structure errors belong to the export step, not to the writing step. If you plan and draft chapters in a Notion workspace, Interactive eBook Builder gives you a Configuration Hub, the Seed Prompt and Agents A, B and C that run in Notion AI (a separate subscription). It prepares content, not EPUB files, so you still export and validate with a separate tool. For format decisions before export, read EPUB vs MOBI vs AZW3, and for the difference between a PDF and a flowing file, see ebook vs PDF.
Conclusion
Match each spine idref to a real manifest id, keep the reading order unchanged, and validate the exported file. The method scales to any book. For a repeatable preparation workflow, Interactive eBook Builder keeps your chapters organized before the export.