Interactive eBook BuilderInteractive eBook Builder
$59 · unlimited access, unlimited eBooksGet it for $59

· Updated · By · 5 min read

EPUB Spine idref Does Not Match Manifest ID: Fix

epubvalidationopftroubleshooting

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:

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?

SymptomLikely causeFix
idref differs by case or a dashTypo or hand editCopy the manifest id into the idref
idref names an item that is not in the manifestChapter deleted or not addedAdd a manifest item or remove the itemref
idref contains a path or extensionFile name used instead of idUse the manifest id
Error returns after every exportTool rewrites IDs or reuses an old OPFFix the source project or export setting
Same id listed twice in the spineCopy and pasteKeep one itemref per item

How do you fix it without changing the reading order?

  1. Back up the EPUB and edit a copy.
  2. Correct each bad idref in place so the position of every itemref stays the same.
  3. If a chapter should exist, add a manifest item with a unique id, the right href and the media type application/xhtml+xml.
  4. If a chapter was removed, delete its orphaned itemref.
  5. Check that no manifest ID repeats and that every href points 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?

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.

FAQ

Should I change the spine idref or the manifest id?

Usually the spine idref, because the manifest defines the items. Change the manifest id only if you rename the item everywhere it is referenced.

Can a manifest item be left out of the spine?

Yes. Images, stylesheets and fonts belong in the manifest but not in the spine. The EPUB 3.3 spec also says the navigation document does not have to be in the spine.

Why does validation pass but my reading order look wrong?

EPUBCheck validates structure, not your intended sequence. Reorder the itemref elements in the spine to match the order you want.

Ship niche eBooks with agents already built.

Get the Interactive eBook Builder for $59