Let me start with something that will save you a lot of self-blame.

Everyone’s first EPUB breaks.

Everyone.

I’ve seen bestselling authors send files that fail validation. I’ve seen publishing houses ship EPUBs with broken navigation. I’ve watched designers stare at an error message for two hours… only to realize it was a missing quotation mark.

EPUB errors aren’t about intelligence. They’re about how fragile the EPUB structure is.

Think of an EPUB like a zip file full of tiny webpages. One bad file path, one missing tag, one image referenced incorrectly — and the whole thing complains.

The trick is knowing where these errors usually hide.

Let’s walk through the ones that trip up new authors over and over.

The #1 Reason EPUB Files Fail Validation

This is the big one.

Broken file paths.

Your EPUB is a folder structure pretending to be one file. Inside it are HTML files, images, stylesheets, fonts, navigation files, and metadata.

When something points to the wrong place, validation fails.

Example of a typical problem:

<img src="images/cover.jpg">

But the real file location is:

Images/Cover.jpg

See the difference?

uppercase letters
folder name mismatch
filename mismatch

Computers treat those as completely different files.

And EPUB validators are ruthless about this.

Quick things to check

Image names match exactly
Folder names match exactly
No spaces in filenames
No strange characters

I once fixed an EPUB where the problem was a single space:

cover image.jpg

Renamed it:

cover-image.jpg

Error gone.

The Error Message Everyone Sees First

Most people meet this one early:

Error Message	What It Actually Means
ERROR(RSC-005): file not found	Something references a file that doesn’t exist or is misnamed
ERROR(OPF-003): manifest item missing	A file exists but isn’t listed in the EPUB manifest
ERROR(NAV-004): navigation document missing	The EPUB has no valid table of contents
ERROR(RSC-007): reference to non-existent resource	Broken link inside HTML

The validator sounds dramatic. The fix is usually simple.

Almost always a path issue or missing file registration.

The Manifest Problem Most People Miss

Inside the EPUB is a file called:

content.opf

This file lists every single file in the book.

Images
chapters
CSS
navigation files
fonts

Everything.

If a file exists but isn’t listed in the manifest, the EPUB fails validation.

Here’s the part new authors overlook:

They add a new chapter HTML file.

But forget to add it to the manifest.

Result?

Validator throws errors.

Example manifest entry:

<item id="chapter5" href="chapter5.xhtml" media-type="application/xhtml+xml"/>

Miss that line? EPUB breaks.

When Images Trigger Errors

Images are a minefield.

Common mistakes I see constantly:

PNG saved in CMYK
JPEG with strange metadata
Image size too large
Missing media-type declaration

Here’s the safe approach.

Use only:

JPG
PNG

And compress them before embedding.

Typical clean entry inside the manifest:

<item id="cover-image" href="images/cover.jpg" media-type="image/jpeg"/>

Another thing people forget?

Declare the cover properly.

Your OPF should include:

<meta name="cover" content="cover-image"/>

Otherwise many readers won’t recognize it.

CSS Errors That Quietly Break EPUBs

CSS problems don’t always scream loudly. They just cause weird rendering.

Typical ones:

unsupported CSS properties
web CSS copied directly into EPUB
missing font references
invalid units

Example mistake:

position: fixed;

Most e-readers ignore it.

Or this one:

vh
vw

Viewport units don’t work well on many EPUB readers.

Safe CSS tends to be boring.

And boring works.

Stick to:

margins
font sizes
line height
simple classes

The Navigation File Problem

Older EPUB2 books used something called an NCX file.

EPUB3 replaced it with an HTML navigation document.

Sometimes books include the wrong one… or both… incorrectly.

Your EPUB3 nav file should look like this:

<nav epub:type="toc">

Inside it should be links to each chapter.

If the navigation file isn’t declared properly in the OPF, the validator throws:

NAV-004

Simple fix:

Make sure the nav file is listed like this in the manifest:

properties="nav"

The Weirdest Error I Ever Saw

True story.

A book kept failing validation with a mysterious XML error.

Everything looked correct.

Files were perfect.

Validator still screamed.

The culprit?

A smart quote pasted into metadata.

Instead of:

The file contained:

“

XML hates those.

Replacing the character fixed everything.

So if you see strange XML errors, check:

quotation marks
apostrophes
invisible characters

They sneak in through Word processors all the time.

The 5-Minute Diagnostic I Teach Every New Publisher

When an EPUB fails, run through this mental checklist.

Check the file structure first.

Then the manifest.

Then HTML errors.

Then images.

Then navigation.

In that order.

Here’s the fast scan I use:

• Run the EPUB through EPUBCheck
• Look at the first error only (later errors are often caused by the first)
• Open the referenced file
• Check file path
• Check XML syntax

Nine times out of ten, the first error reveals the real issue.

Tools That Make EPUB Errors Much Easier to Fix

You don’t want to debug EPUBs blind.

These tools help tremendously.

Tool	Why It Helps
EPUBCheck	Official validator used by most platforms
Sigil	Lets you edit EPUB files directly
Calibre Editor	Excellent for fixing structure and CSS
Kindle Previewer	Shows rendering problems instantly

Open the EPUB inside Sigil or Calibre and you can see the internal files clearly.

That’s when things start making sense.

The One Thing I Wish New Authors Knew

Here’s the truth.

Word processors are terrible EPUB generators.

They produce messy HTML.

Extra spans
inline styles
unnecessary markup

The cleaner your HTML is, the fewer EPUB errors you’ll see.

A clean chapter file should look simple:

<h1>Chapter One</h1>
<p>Text begins here...</p>

Nothing fancy.

Just structure.

When Everything Looks Fine But The EPUB Still Fails

Sometimes the problem hides deeper.

Check these less obvious causes:

• duplicate IDs in HTML
• missing closing tags
• incorrect MIME type in OPF
• font licensing restrictions
• corrupted zip structure

And occasionally…

The EPUB was zipped incorrectly.

Yes, that happens.

The mimetype file must be first and uncompressed.

Many zip tools mess that up.

Still Stuck? The Nuclear Option

If the EPUB is a mess and debugging feels endless, here’s the reset move I use.

Extract the EPUB.

Rebuild it clean.

Steps:

Unzip the EPUB.
Create a new EPUB project in Sigil.
Import chapters one by one.
Add images manually.
Rebuild the table of contents.

Takes about 20 minutes.

But it wipes out dozens of hidden errors instantly.

Sometimes rebuilding is faster than hunting ghosts.

What Happens After You Fix These

Here’s the good news.

Once you understand:

file paths
the manifest
navigation
clean HTML

EPUB errors stop being mysterious.

They become mechanical.

Something breaks.

You check the structure.

You fix the reference.

Validator goes green.

That moment when EPUBCheck says “No errors found.”

That’s when you know the book is ready.