EPUB Table of Contents Not Working? Use This Repair Workflow

When an EPUB TOC fails, readers lose navigation and trust in the file. This guide gives you a clear path: identify the exact symptom, isolate likely causes, apply targeted fixes, and validate on multiple readers.

Start with Symptom Classification

Do not jump directly into editing XML. First classify what is broken:

• TOC missing: no table of contents is shown at all
• TOC visible but empty: panel appears with zero entries
• Entries present but links fail: clicking does nothing or jumps wrong
• Partial TOC: only some chapters appear
• Wrong labels: chapter titles are incorrect or duplicated

Know the Two TOC Systems

1) EPUB3 Navigation Document (`nav.xhtml`)

Modern readers prioritize this HTML-based navigation.

2) EPUB2 NCX (`toc.ncx`)

Older readers still depend on NCX. For broad compatibility, many production EPUBs include both.

Fast Triage (5 Minutes)

1. Open the EPUB in two different readers (for example Calibre + another app).
2. If TOC works in one reader but not another, you likely have compatibility formatting issues.
3. If TOC fails everywhere, inspect structure and links.
4. Run EPUB validation before manual edits.

Primary Causes and Exact Fixes

Cause A: Broken Href or Anchor IDs

TOC links point to files/anchors that do not exist after chapter renaming or cleanup.

• Check each link target in `nav.xhtml` and `toc.ncx`.
• Confirm the chapter filename and `id` still exist.
• Normalize anchors (`chapter-01`, `chapter-02`) for consistency.

Cause B: Missing Manifest/Spine References

If content files are not properly listed in OPF manifest/spine, readers may skip TOC targets.

• Open OPF package file.
• Verify every chapter referenced by TOC exists in manifest.
• Ensure reading order in spine matches expected sequence.

Cause C: NCX Missing in EPUB2 Compatibility Scenario

Some older readers display no TOC if only nav.xhtml exists.

• Generate NCX from headings.
• Re-export EPUB with both nav and NCX where needed.

Cause D: Heading Structure Is Inconsistent

Auto-generated TOC tools rely on heading hierarchy. Mixed heading style causes partial TOC.

• Use consistent H1/H2 patterns for chapters/sections.
• Avoid using styled paragraphs as fake headings.
• Regenerate TOC after heading cleanup.

Calibre Repair Workflow

1. Open ebook in Calibre and launch Edit Book.
2. Run validation and fix reported structural errors first.
3. Open TOC editor and inspect each entry target.
4. Regenerate TOC from major headings if structure is consistent.
5. Save and retest on at least two readers.

Sigil Repair Workflow

1. Open EPUB in Sigil.
2. Inspect `nav.xhtml` list links and anchor targets.
3. Inspect `toc.ncx` navPoints for path mismatch.
4. Regenerate TOC if manual fix becomes too noisy.
5. Validate (`F7`) and retest.

Validation Checklist Before You Ship

• TOC opens and shows all expected chapters.
• Every TOC entry jumps to the right start location.
• No duplicate entries.
• Works in at least one modern reader and one compatibility-focused reader.
• No EPUBCheck-critical errors remain.

When to Stop Repairing and Use a Fallback

If source structure is heavily damaged and deadline matters, convert EPUB to PDF for stable delivery.

1. Open EPUB to PDF.
2. Convert and verify chapter flow visually.
3. Distribute PDF while scheduling EPUB cleanup later.

This is not ideal for reflowable reading, but it is practical for urgent sharing, reviews, and printing workflows.

Prevention Standards for Future EPUBs

• Use semantic headings from draft stage.
• Freeze file naming before final TOC generation.
• Regenerate TOC after any chapter split/merge.
• Validate pre-release every time.
• Keep one “golden reader pair” for consistency tests.

FAQ

Why does TOC work in one app but not another?

Different readers prioritize different navigation systems and tolerate different structural errors.

Do I always need both nav.xhtml and toc.ncx?

Not always, but including both improves compatibility across legacy and modern readers.

Can conversion fix TOC automatically?

Sometimes. Re-conversion can rebuild structure, but broken source headings usually still require manual cleanup.