calibre EPUB Validation Failed: What It Means and How to Fix It

You created an EPUB with calibre, opened it successfully, and perhaps even read several chapters without noticing a problem. Then EPUBCheck, an online validator, or an e-book store reported that the file was invalid. This does not necessarily mean calibre is broken or that the entire book must be rebuilt. It usually means the EPUB contains malformed XHTML, invalid CSS, missing resources, incorrect metadata, broken links, packaging errors, or content that does not meet a retailer's additional delivery rules. The important distinction is that a readable calibre-produced EPUB is not guaranteed to satisfy every strict validation pipeline. calibre conversion prioritizes producing a usable e-book from many possible input formats, while a publishing validator checks detailed conformance requirements. The practical solution is to identify the first meaningful error, fix it, save a new copy, and test again before changing anything else.

1. Confirm the Symptom With a Small Safe Test

Before editing the book, confirm which file failed and which tool rejected it. A surprisingly common problem is validating an older exported copy while editing a newer copy inside the calibre library.

1. In calibre, select the affected book.
2. Confirm that EPUB appears in the available formats.
3. Use Save to disk to export a fresh copy into a new local folder.
4. Give the exported file a simple name such as validation-test.epub.
5. Run that exact file through the validator that reported the problem.
6. Save the complete error report before making changes.

Avoid testing a copy stored in an email attachment, browser download folder, cloud synchronization conflict folder, or device directory. Those locations can contain renamed, cached, incomplete, or outdated copies.

Success at this stage means you can reproduce the same validation result with a known file stored locally. If the fresh export passes, stop changing conversion settings. The earlier failure probably involved the wrong copy, an incomplete transfer, or a store-specific requirement rather than the EPUB currently stored in calibre.

1.1 Separate Errors From Warnings

Validators commonly distinguish between errors, warnings, and informational messages. An error generally indicates that the publication does not conform to a required rule. A warning may identify a compatibility, accessibility, or quality concern without making the EPUB structurally invalid.

Start with the first error in the report, especially when later messages refer to the same XHTML, CSS, OPF, navigation, or image file. One malformed element can produce dozens of secondary messages. Fixing the earliest structural problem may remove many later errors automatically.

1.2 Compare With a Minimal Conversion

If you are unsure whether the source or your saved conversion settings caused the problem, create a temporary conversion using default or nearly default settings. Do not overwrite your working EPUB. Convert the original source into a separate test EPUB, export it, and validate it.

• If both EPUBs fail at the same location, inspect the source content.
• If only the customized conversion fails, review the changed conversion options.
• If the minimal EPUB passes, preserve it and reintroduce necessary changes one at a time.

Success means you have narrowed the failure to either the source, the conversion configuration, or later editing. Once the responsible stage is clear, stop testing unrelated calibre features.

2. Check the calibre Features Directly Related to Validation

An EPUB validation failure is normally an internal book-content problem. Device detection, email delivery, the Content server, news downloads, and library display preferences do not normally determine whether XHTML or CSS inside an EPUB is valid. Investigate those features only when they may have changed, replaced, or transferred the file being tested.

2.1 Use Edit Book and Check Book

Select the book in calibre, open Edit book, and choose Tools > Check book. This tool can identify malformed HTML, invalid or unknown CSS, broken internal links, unreferenced files, and common package-document problems.

Work through the results in this order:

1. Malformed XHTML or XML errors.
2. Missing files, broken links, and manifest problems.
3. CSS syntax errors.
4. Navigation, table-of-contents, spine, and metadata errors.
5. Compatibility warnings and optional cleanup items.

Double-click an error to open the affected location. If calibre offers an automatic fix, create or confirm a checkpoint first. Automated HTML repair can be useful, but fault-tolerant parsing may interpret badly damaged markup differently from the author’s intention. Review the chapter in the preview after applying a fix.

Success means Check book no longer reports the targeted error and the affected chapter still looks and navigates correctly. Save the EPUB, export a fresh copy, and run the external validator again. Do not continue rewriting valid files simply to make the Check book list empty if the remaining entries are unrelated warnings.

2.2 Fix XHTML Errors at Their Source

EPUB content documents are generally XHTML, not arbitrary browser-tolerated HTML. Web browsers and e-book viewers may display malformed markup by silently repairing it. A strict validator may reject the same markup.

Typical XHTML problems include:

• An opening tag without a matching closing tag.
• Elements closed in the wrong order.
• An unescaped ampersand in text or a URL.
• Duplicate IDs within one document.
• Invalid attributes copied from a word processor or website.
• Incorrect namespace declarations.
• Characters stored with an unexpected encoding.
• Links pointing to files or fragment IDs that do not exist.

For example, a visible ampersand in XHTML may need to be represented as & in the source. A paragraph opened inside another paragraph may need to be separated into two correctly formed elements. A link ending in #note7 must point to an element that actually has the corresponding ID.

If the same malformed pattern appears throughout the book, use a carefully scoped search and replace instead of fixing hundreds of files manually. Test the replacement on one file, inspect the result, and create a checkpoint before applying it across all text files.

Success means the corrected document opens without new Check book errors, displays as intended, and no longer appears in the external validator report.

2.3 Correct Invalid CSS Without Destroying the Design

CSS errors may come from pasted website styles, exported word-processing documents, hand-written rules, or conversion artifacts. Look for missing braces, malformed property declarations, invalid selectors, unsupported values, stray HTML inside a stylesheet, and references to missing font or image files.

Do not delete the entire stylesheet as a first response. That can remove indentation, spacing, alignment, page-break behavior, and other necessary formatting. Instead, open the exact stylesheet and line identified by the validator. Correct or remove the smallest invalid declaration, then preview representative pages.

If a store rejects a technically valid feature that it does not support, follow that store's publishing guide. Store ingestion rules may be narrower than the general EPUB specification.

Success means the CSS error disappears while headings, paragraphs, lists, images, and scene breaks retain their intended appearance. At that point, stop modifying the stylesheet unless another specific error points to it.

2.4 Review Metadata and Package Information

Metadata displayed in the calibre library is not always identical to the package metadata embedded in a previously exported EPUB. Before reconverting, verify the title, author, language, identifier, cover, and other required fields. Then make sure your new output actually incorporates the corrected metadata.

Metadata-related failures may involve a missing language, malformed identifier, duplicate package entries, an invalid cover reference, or a manifest item that does not match the packaged file. Use Check book to locate package-document problems rather than repeatedly editing the visible title and author fields without evidence.

Success means the validator no longer reports the package or metadata error and the exported file displays the correct title, author, language, and cover in a separate reader.

2.5 Review Conversion Options and Output Choices

calibre converts many source formats through an internal pipeline that produces XHTML before creating the final EPUB. This is convenient, but conversion alone is not a promise that poorly structured source material will become a publication-ready EPUB.

Review options that can directly alter the book's structure:

• Search and replace rules that inject or remove markup.
• Extra CSS containing a syntax error.
• Structure detection expressions that split content incorrectly.
• Table-of-contents generation settings.
• Heuristic processing that makes unwanted structural changes.
• Page-break or chapter-marking options.
• Output format and EPUB-specific options.

Device output profiles primarily influence presentation and sizing. They are not a general repair switch for validation failures. Choose an appropriate profile when necessary, but do not cycle through device profiles hoping malformed XHTML will become valid.

Success means a controlled conversion no longer introduces the reported error. Once you identify the responsible option, leave unrelated conversion settings unchanged.

2.6 Check Plugins Only When They Touch the EPUB

A plugin matters only if it participates in import, conversion, metadata processing, polishing, editing, export, or device transfer. Temporarily disable a relevant third-party plugin and repeat the same conversion or export. Do not disable every plugin at once unless you are running a clean isolation test.

If the EPUB passes without the plugin, review the plugin's configuration and update path before using it again. If the result is unchanged, re-enable it and move on. A viewer theme, unrelated library utility, or device plugin that never handled the tested file is unlikely to cause an XHTML validation error.

3. Check the Source File and Operating System Handoff

3.1 Start With the Cleanest Available Source

Source quality strongly affects conversion quality. A well-structured DOCX, HTML, or existing EPUB is more likely to produce clean results than a PDF, copied web page, OCR output, or document assembled from many applications.

When possible, clean the source before reconverting:

• Use real heading styles instead of enlarged body text.
• Remove empty paragraphs used only for spacing.
• Correct broken lists and tables.
• Delete hidden pasted web elements.
• Use consistent paragraph styles.
• Confirm that images are available and not linked to temporary locations.
• Export clean HTML with valid XHTML-compatible structure when using HTML input.

A PDF is designed around page appearance rather than semantic e-book structure. Converting one may require extensive cleanup of paragraphs, headers, footers, hyphenation, and reading order. If an editable original exists, use it instead.

Success means the new conversion contains simpler XHTML, fewer validator messages, and correctly structured chapters. If it passes validation and looks right, do not keep reconverting it.

3.2 Rule Out Permissions, Cloud Sync, and File Replacement

Operating system problems rarely create a specific CSS syntax error, but they can prevent calibre from saving the corrected file or cause you to validate an older copy. Export to a normal writable folder on the local disk. Avoid a protected application directory, read-only device volume, shared network path, or cloud folder during diagnosis.

On Windows, confirm that security software is not blocking calibre's temporary files or quarantining an exported file. On macOS, verify that calibre has access to the selected folder. On Linux, confirm ownership and write permissions for the destination and temporary directories.

Pause cloud synchronization only if it is creating conflicted copies, locking the file, or restoring an older version. Re-enable it after the test. Do not broadly disable antivirus or firewall protection for an XHTML validation error. Those controls are relevant only when logs show that calibre cannot read, write, or replace the output file.

Success means the file's modified time changes when you save it, its size remains stable after export, and the validator is receiving the same local file you just edited.

3.3 Understand Device, Email, and Server Limitations

USB mode, device detection, email settings, and Content server options do not repair EPUB markup. They become relevant when the EPUB passes locally but fails, disappears, or changes after delivery.

• Validate the local file before sending it to a device.
• Compare the local file with the transferred copy if a device workflow modifies formats.
• Download the book from the Content server and validate that downloaded copy if server delivery is in question.
• Save an emailed attachment locally before testing it.
• Check attachment limits if email delivery truncates or rejects the file.

If the local EPUB fails, return to Edit book. If the local EPUB passes but a transferred copy fails, troubleshoot the transfer path instead of continuing to edit valid content.

4. Use calibre Logs and Conversion Debug Output

Logs are most useful when the conversion completed but you need to know what calibre changed. Open the Jobs panel and double-click the completed conversion job to view its detailed log. Look for warnings about failed resource loading, unsupported input, missing images, malformed markup, character encoding, or transformation rules.

4.1 Inspect the Conversion Pipeline

calibre can save intermediate content from different stages of its conversion pipeline. Enable conversion debug output and choose an empty folder. The resulting folders let you compare the initially imported content with the processed XHTML supplied to the output plugin.

Use this comparison to answer a specific question:

• Was the invalid markup already present immediately after import?
• Did structure detection introduce the problem?
• Did a CSS transformation produce the invalid rule?
• Did the final packaging stage omit or misreference a resource?

If the earliest intermediate XHTML is already malformed, clean the source or import stage. If it is initially correct but becomes invalid later, review the conversion option associated with that stage.

Success means you can identify the first stage where the error appears. Stop examining later stages once the origin is established.

4.2 Use calibre-debug Only for Application-Level Failures

The calibre-debug command can launch calibre components with debugging enabled. It is useful when the editor crashes, the graphical interface does not complete an operation, a plugin throws an exception, or no useful job details are available. It is usually unnecessary for an ordinary validator message that already names a file and line.

Run command-line debugging from a terminal or command prompt only if you are comfortable copying the exact output. Paths containing spaces should be quoted. Preserve the original EPUB and avoid experimenting inside the live calibre library folder.

Device-detection debugging is appropriate when calibre cannot recognize a connected reader. It does not diagnose malformed XHTML in an EPUB that already exists on your computer.

5. Run a Clean Temporary Test Before Reinstalling

Reinstalling calibre rarely fixes invalid content stored inside one EPUB. Deleting the library is even less appropriate and risks losing organization or data without correcting the book. First run a clean, reversible test.

1. Copy the original source file and affected EPUB to a temporary local folder.
2. Create a temporary calibre library rather than modifying the main library.
3. Add only the source file.
4. Use default conversion settings.
5. Do not apply optional plugins or automated metadata changes.
6. Run Edit book and Check book.
7. Export the result to another local folder.
8. Validate that exact export.

If the clean result passes, compare it with the failing EPUB and reintroduce required settings one at a time. If it fails with the same errors, the source content probably needs correction. If calibre itself crashes or cannot write any output in the clean environment, application installation, permissions, temporary-folder access, or security software becomes a more plausible cause.

After every repair, save, export, and validate again. Do not apply ten fixes before retesting. A one-change-at-a-time process tells you what worked and prevents a valid book from being damaged by unnecessary cleanup.

6. Quick Fix Checklist

• Export a fresh EPUB to a simple local folder.
• Confirm the validator is testing the newest file.
• Save the complete validation report.
• Fix the first structural error before later warnings.
• Open Edit book and run Tools > Check book.
• Correct malformed XHTML and broken internal links.
• Repair the smallest invalid CSS rule instead of deleting all styles.
• Verify language, identifier, cover, manifest, spine, and navigation data.
• Review Extra CSS, search-and-replace, structure detection, and heuristic options.
• Use clean source material instead of expecting conversion to repair everything.
• Test without EPUB-altering third-party plugins when relevant.
• Use job details and conversion debug output to find the first bad stage.
• Validate after each fix.
• Check the target store's current delivery rules.
• Stop changing settings when the validator passes and the book renders correctly.

7. Frequently Asked Questions

7.1 Why Does the EPUB Open If It Is Invalid?

E-book viewers often tolerate or silently repair malformed markup. Validators apply formal EPUB rules and may reject content that a viewer displays successfully. Readability is an important test, but it is not proof of specification conformance or store acceptance.

7.2 Does calibre Guarantee a Publish-Ready EPUB?

No. calibre is highly capable at converting and managing e-books, but its conversion system accepts many imperfect source formats and aims to create usable output. Publishing normally requires validation, visual proofing, metadata review, accessibility review, and checks against the target retailer's requirements. Conversion should be treated as a starting point for production cleanup, not the final quality-assurance step.

7.3 Is Check Book the Same as EPUBCheck?

No. calibre's Check book is an integrated editing and troubleshooting tool that catches many markup, CSS, link, resource, and package problems. EPUBCheck evaluates EPUB publications against the official EPUB specifications. Use Check book to locate and repair issues, then run EPUBCheck or the store's required validator on the exported file.

7.4 Should I Convert the EPUB to EPUB Again?

An EPUB-to-EPUB conversion can rebuild content and occasionally remove some problems, but it may also alter styling, navigation, metadata, or document structure. Keep the original and use Edit book first when the validator identifies a precise XHTML, CSS, or package error. Reconvert only when testing shows that the conversion pipeline provides a cleaner foundation.

7.5 Why Does EPUBCheck Pass but the Store Still Rejects the File?

A retailer may apply additional ingestion, metadata, image, navigation, encoding, feature, or content rules beyond baseline EPUB conformance. Read the store's exact error and current asset guide. Fix the retailer-specific requirement without assuming that a general EPUBCheck pass guarantees acceptance everywhere.

7.6 When Should I Stop Troubleshooting?

Stop changing settings when the current exported file passes the required validator, opens in representative reading software or hardware, preserves navigation and formatting, and meets the destination store's submission rules. Save that successful file separately. Further cleanup without a defined problem can introduce new errors and make the result harder to reproduce.