EPUB 3 · Troubleshooting guide

Fix EPUBCheck RSC-007 and RSC-012

A missing chapter, a broken footnote and a missing cover can look surprisingly similar in a validation report. Start with the location EPUBCheck gives for the failing reference.

RSC-007 · Missing resource: The linked file could not be found at the specified path inside the EPUB. The cause might be a misspelled filename, an incorrect folder or a missing asset.
RSC-012 · Undefined fragment: The link points to an identifier that is undefined at its destination. In a chapter link such as west.xhtml#west, check the part after # against the intended heading’s id.

Find the link that failed.

Open a copy of the EPUB in an editor such as Sigil. The filename and line or column beside the error identify where EPUBCheck saw the reference. For RSC-007, the filename in the message identifies the missing target. These can be different files.

A navigation document may be named nav.xhtml, contents.xhtml or something else. Find the chapter entry’s <a href="…"> inside <nav epub:type="toc">. Even in that file, a <link> to a stylesheet or an <img> pointing to artwork requires a different repair.

Repair a contents link on a copy.

Preserve the source. Keep the original EPUB. If you generate it from another project, back up that project too. Apply the correction in the source you will use for future exports.
For RSC-007, find the existing chapter. In your editor’s book browser, locate the chapter by its visible heading. Compare its filename, capitalization and folder with the TOC entry’s href. Paths are relative to the navigation file. For example, from EPUB/nav.xhtml, a chapter at EPUB/Text/west.xhtml uses Text/west.xhtml. If the chapter is genuinely absent, recover it from the source before editing a link.
For RSC-012, inspect the heading ID. In the intended chapter’s source, find the exact heading. For <h1 id="west">, the link ends in #west. Match spelling and case. If the heading lacks an ID, a source editor can assign a unique one and update its references. Repointing a link to a different heading simply to clear the error can send readers to the wrong place.
Test what the reader sees. Save or export a new EPUB, run EPUBCheck on that file and review the complete result. Open the corrected file in your ebook reader and select the affected chapter from Contents. Confirm the opening heading and first lines, then try a neighboring entry.

If the error is elsewhere

Footnote or chapter cross-reference. Inspect the link in the chapter that made the reference. Check the destination file and the target ID. For a footnote, test the jump and its return link in a reader.

Cover, artwork or styles. Inspect the reported reference and verify the referenced asset is packaged at that relative path. For a manifest entry, resolve its path from the package document. Restore an omitted asset from your source or correct its reference, then export and validate again.

For several unrelated errors, an encrypted file or a fixed-layout book, start with the original source project or ask its formatter to review the full validation report privately.

Illustrative checks

These examples come from running EPUBCheck 5.4.0 on variations of our fictional book. The same code can lead to different repairs.

RSC-007 in Contents. The entry pointed to west-old.xhtml. The chapter was named west.xhtml.
RSC-012 in Contents. The chapter existed, but its heading used id="west" and the entry requested #west-old.
RSC-007 in a chapter. Its image referenced the missing lost-tide.png.
RSC-007 in the navigation file’s head. A stylesheet link referenced the missing missing-style.css. Both chapter entries still worked.
RSC-012 in chapter text. A link in a paragraph requested an undefined ID in another chapter.

Inspect the repaired fictional ebook and its report.

Tools and references