Read EPUBCheck errors before changing your manuscript

Keep the file and report together

An error code on its own is rarely a complete repair instruction. Save the exact file name or version, the validator version, the full message and every reported location. A report from an earlier export may point to text or IDs that have already changed. Do not assume two similarly named EPUBs contain the same bytes.

Start with the tool that produced the warning. A publisher can wrap EPUBCheck output in its own interface and apply additional submission rules. If a local run and a publisher disagree, compare the exact file, validator version and complete diagnostic before rebuilding the book. Keep a private copy of the report; it may contain your title, metadata and source context.

Draft2Digital says Invalid Epub: what to check next

Draft2Digital distinguishes a repaired EPUB from an invalid EPUB. Its knowledge base says it attempts common repairs: a Repaired Epub warning means corrections were made, while an Invalid Epub warning means automatic repair did not resolve the validation failure. An invalid file can still proceed to some destinations, but stores that require a valid EPUB are unavailable. Check the current Draft2Digital explanation and your selected stores rather than treating every warning as a complete publication ban.

Start with the exact EPUB you submitted and the full diagnostic, not just the warning banner. The following is a troubleshooting workflow, not a ChapterTidy test of Draft2Digital acceptance or a guarantee that a retailer will approve the book.

• Record the message code, severity, complete text and every internal file location. If the interface exposes a validator version, record that too. Keep the report private; paths and context can reveal unpublished material.
• For RSC-012, inspect the link destination file and the fragment after #. A contents entry or footnote link can point to an ID that does not exist. Confirm the intended target before changing it. A working outward footnote link does not prove its return link is correct.
• For RSC-005, read the explanation after the code. It is a parsing category, not a universal duplicate-ID diagnosis. Compare the complete message with the verified examples below before editing markup.
• Make a focused correction in the source document or EPUB editor, export a new file, and validate that exact version. Compare file versions if a local result and the distributor report disagree; do not assume either report describes a later export.
• After revalidation, open the final EPUB and test chapter links, notes and return links. If a distributor warning remains, preserve both reports and use the official support route with the smallest relevant diagnostic, not a public copy of your manuscript.

• See the verified missing-fragment and duplicate-ID examples
• Check footnote destinations and return links
• Open the official Draft2Digital EPUB validator (external upload service)

Find the detailed report in ChapterTidy

ChapterTidy runs EPUBCheck on generated EPUB output. In Exports & reports, expand Automatic check details to find the EPUBCheck specification check. The main list shows the check name and status, not a separate table of every validator message.

Choose Download report, open the HTML report in your browser and expand its JSON section. Inside checks, find the entry whose code is epubcheck. When the validator produced a report, the original JSON is under evidence.report. That report contains messages and checker information. ChapterTidy source_issues are separate application findings, with codes such as broken_link; they are not EPUBCheck message IDs.

The JSON status not_run appears as Not checked in the English interface; failed appears as Could not complete. A not_run status is not a pass. It can mean the tool was unavailable or validation did not complete. A failed required EPUBCheck result blocks the export download; it is not something to dismiss by marking the book manually reviewed. The report is still useful for diagnosing what needs attention.

Read the fields, not just the error count

In the verified EPUBCheck 5.3.0 JSON below, message IDs use the uppercase field ID. Other interfaces may format the same information differently. Inspect the actual report rather than assuming its labels or layout match this page.

A source path such as EPUB/nav.xhtml names a file inside the EPUB package. Its line and column locate serialized markup, not a printed book page or the paragraph number in your Word source. An editor may write an entire XHTML chapter on one line, so line 1 can still refer to a real problem deep in that file.

On small screens, scroll the table sideways to see all columns.

Two real diagnostics from an original practice file

These examples were produced on 8 November 2026 by the installed official EPUBCheck 5.3.0, using ChapterTidy’s original The Quiet Hours practice EPUB. They are direct validator runs, not customer cases, platform acceptance tests or a claim that the application automatically repairs both defects. No manuscript prose or illustration was changed.

For the clean control, the sample’s navigation link book.xhtml#missing was changed to its existing book.xhtml#quiet destination. That control completed with no errors or warnings. The unchanged sample demonstrates the missing-fragment problem. For the duplicate-ID example, a paragraph in the clean control was given id="arrival", which was already used by a heading.

Download the selected diagnostic evidence below to compare the sample hash, exact mutations, validator version, message fields and file locations. It preserves the results of the 8 November run; it is not a new test or a full raw report. Machine paths and generated runtime context URLs are omitted. The sample itself is original ChapterTidy practice material.

On small screens, scroll the table sideways to see all columns.

• Download the original EPUB practice file
• Inspect an EPUB contents-link problem
• Download the selected EPUBCheck sample evidence (JSON)

RSC-005: locate div not allowed here without guessing

An EPUBCheck message saying element "div" not allowed here is about where that element appears, not a ban on every div in the book. Inspect its parent and surrounding opening and closing tags. A paragraph expects phrasing content; a div containing a paragraph is not the same structure as a div placed inside a paragraph. Do not delete the text inside an element to silence the message.

Open a separate working copy in an EPUB editor with a code view, select the exact internal XHTML path named in the report, then go to the reported line and column. EPUB/book.xhtml is a file inside the EPUB, not page 9 of a printed book. Read several surrounding lines and find the containing element. A missing or misplaced boundary can make a later tag the point where the validator notices the problem.

On 12 November 2026, we tested four controlled variants of ChapterTidy's original The Quiet Hours sample with official EPUBCheck 5.3.0. The control corrected the existing missing navigation destination to #quiet and put adjoining tags on separate lines. We then wrapped its unchanged first paragraph as p > div.scene > p. The table reports the actual results. The comparison kept normalized text and the illustration bytes unchanged; it is not an Affinity export, a customer case or an IngramSpark acceptance test.

The same invalid fixture was uploaded to ChapterTidy and generated in Repair in original format with no repairs selected. The source issue list showed the sample's heading and contents issues, not a complete EPUBCheck diagnosis. The export showed Could not complete and Download blocked by failed checks. Its downloaded report preserved RSC-005 at EPUB/book.xhtml, line 9, column 20. This run confirms a blocked invalid export, not an automatic nesting repair. Use the detailed report even when the initial issue count looks small.

An individual author reported this wording after an Affinity export was rejected by IngramSpark. That discussion motivated this example, but neither the vendor bug's current status nor that author's file was verified here. A correction that fits one wrapper structure must not be applied across unrelated files.

• Read the full RSC-005 message. Duplicate IDs, invalid nesting and other parsing defects need different corrections even when the message code matches.
• If a wrapper is misplaced, correct the specific nesting while retaining its intended text, IDs, classes and references. The p > div > p example below was corrected to div > p, not by deleting its paragraph.
• Do not globally replace div with span. In our counterexample this simply moved the error to the paragraph inside the span. Changing an element can also affect styling and meaning.
• Save a new EPUB, rerun validation on that exact file and inspect the affected passage, images and navigation in a reader. Passing the controlled example does not prove another manuscript is visually or structurally correct.
• If you cannot identify the intended structure, keep the original and ask the authoring-tool support team or a formatter to inspect a minimal excerpt. Do not publish an unpublished manuscript or raw private report.

On small screens, scroll the table sideways to see all columns.

• Find the complete EPUBCheck report in ChapterTidy
• Compare the separate duplicate-ID example
• Download the original practice EPUB, not an author's manuscript

Choose a focused correction, then validate again

For a missing fragment, check the target file and the ID after the # character together. A heading can exist while the link points to a different or nonexistent ID. Restore the intended target or correct the reference only after confirming where the link should go. Do not invent a destination merely to remove an error.

For a duplicate ID, inspect every reported occurrence in that content file. Give distinct elements appropriate unique IDs and update links that actually reference the changed target. Do not delete prose, a heading or an entire stylesheet just to silence a validator message. If you cannot safely edit the EPUB source, return to the authoring document or use an EPUB editor or formatter.

After a small correction, regenerate the EPUB if needed and validate that new file. A parsing problem can produce follow-on diagnostics, and one grouped message can carry multiple locations. The number of message objects is not necessarily the number of locations or separate editing tasks. Keep the original and compare text, images and navigation after the change.

Separate severity, versions and platform rules

Read the severity in the actual report alongside the full message. Fatal errors, errors, warnings and informational messages are different categories. Informational output is not automatically a publication-blocking defect, while a warning still deserves inspection in context. A platform can impose requirements beyond an EPUBCheck run.

For example, the current official message reference lists CSS_007 as informational. An author discussion describes confusion when a CSS-007 message appeared within a distributor’s Errors panel. That is evidence of a confusing presentation, not proof that this code always blocks publication, that the publisher is wrong, or that a particular repair is safe. Check the validator version and the publisher’s explanation.

RSC-005 is a general parsing message. Our controlled example reports a duplicate ID, but another RSC-005 can describe a different markup problem. Read the detail after the colon instead of applying a search-result fix solely because the code matches.

Finish with the exported book, not only a green status

A passed EPUBCheck result addresses the checks performed by that validator. It does not establish that the contents links go to the chapter you intended, that the text is complete, that fonts and images look right on every device, or that an accessibility or retailer review will pass.

ChapterTidy can help inspect contents links and structure, apply supported repairs and produce a report. It does not offer a universal repair for every EPUBCheck diagnostic. For unsupported package or markup edits, use the source authoring workflow or an EPUB editor, then return with the revised file. Open the actual export in the target reader or publishing previewer, click the navigation and inspect any remaining review items.

If the same exported file behaves differently in a platform previewer, preserve the exact warning and the comparison results. Use those details when asking the platform or your formatter for help. Never post your full unpublished manuscript or raw private report merely to ask what an error code means.

• Compare file problems with KDP preview warnings
• Read how ChapterTidy handles uploaded files