Your ePub Is Fine. Kobo Disagrees. Blame Adobe

[drop_cap]A[/drop_cap]dobe isn’t exactly a beloved company these days. People begrudgingly use their stuff, because the Creative Suite is an industry standard (read: monopoly) or there are simply no worthwhile alternatives, not because anyone is genuinely excited about these tools.

I’m happy to report that I (mostly) make do without Adobeware these days (shoutout to Photopea), and yet, my disdain of Adobe just reached a completely new level.

Let me explain.

A while back I published a new book. As always I gave readers direct access to DRM-free EPUB files, which go through a gauntlet of processes until they pass all epubcheck … err … checks.

If you’re not familiar with epubcheck, it is basically the gold standard for well-formed ebooks. It can be very annoying at first, because it’s more pedantic than a nun on Ash Wednesday. If your manifest doesn’t meticulously account for every snippet and image in your book, your epub shall not pass. If you use html elements out of order, if your document diverges in the slightest from the holy set of rules decreed by the International Digital Publishing Forum, you won’t pass.

So yeah. Getting an epub to 100% epubcheck is no small feat for beginners. When I started out, I dreaded the moment when I hit the validate button on my finished book after months of work, because it would always find something to cry about.

These days however, I’m a big fan of epubcheck. Why? It’s the closest thing us publisher-types have to a ‘type-linter’ or formal testing suite. In other words, if your book passes epubcheck you are guaranteed that the book will work on any EPUB-compatible reader or app.

Or at least, that’s the idea.

I recently received a message from one of my readers that my new book, which passed epubcheck ruleset 3.3 with flying colors, was “corrupted”.

Backwards compatibility perhaps? So I gave them an EPUB2 version, also fully rule-compliant. And yet the same issue occurred. They told me the book wouldn’t open on any of their Kobo devices from various generations.

So what do you do when the pedantic gold standard of epubcheck says your book is fine, when it works without issue on Amazon Kindle, Apple Books, Thorium and everywhere else and yet Kobo says it’s “corrupted”?

I dug into this matter and found out that Kobo uses RMSDK, “Reader Mobile Software Development Kit”, Adobe’s proprietary ebook rendering engine.

Perhaps you see where this is going …

RMSDK is the guts of Adobe Digital Editions (that bloated pinnacle of software that is 80% about DRM, 20% about the reading experience), the engine on various Kobo devices and older Sony/Nook devices. Originally built around 2010 (!) for EPUB2, it was lightly updated for EPUB3 but never modernized.

While that realization didn’t solve the issue for me (epubcheck still said “yay” while Kobo said “nay”), it at least gave me a path towards debugging.

And so I threw my book into Adobe Digital Editions. As expected, it failed to load. But how! Without an error message, without the slightest whimper. The book just wouldn’t load. The only sign that it had even tried was that when loading it again ADE told me: “you can’t import that book, you already added it”. While showing a white screen.

Classic Adobe.

So I started ripping my book apart, creating a dozen different variations, always making sure that epubcheck still passed. I rearranged folder structures, gutted metadata, nuked language attributes, generated epubs with fresh UUIDs, flattened directories, renamed extensions, rebuilt the zip from scratch a dozen times, and shook up my manifest.

And it failed. And failed. And failed.

While I had almost given up it occurred to me to disable the stylesheet. And eureka, suddenly it loaded!

Once the stylesheet was identified as the source of my woes, I could finally drill down to find which specific line was causing the issue. After creating a dozen more variations with different subsets of my stylesheet I eventually identified the culprit. It was this line:

.copyright img {
    max-width: min(150px, 30vw);
}

Once I changed it to the more old fashioned max-width: 150px; ADE opened it just fine.

But what is the problem here? The above code is perfectly valid CSS level 4, it’s just not supported by RMSDK, because its CSS parser is frozen in approximately 2013 — no flexbox, no grid, no math functions, no custom properties. Just good old float, bad font handling, and silent crashes when it sees anything it doesn’t recognize.

So why didn’t epubcheck catch it?

Epubcheck does basic CSS checking of course, but it can’t validate CSS against a renderer which is fundamentally broken!

So there you have it.

It’s the year 2026. Thanks to the horrendous RMSDK which Kobo decided to use as their backbone for all book rendering (probably for DRM reasons), a single line of perfectly valid CSS turns a perfectly valid EPUB file into a “corrupted file” on Kobo and just drops the whole book. No clear error message, no fallback. Just a massive fail.

I’ve since published a new version so none of my readers have to ever stumble over this issue again.

In a perfect world, RMSDK would just stop living in the CSS stone-ages or at least provide some kind of error handling instead of dropping the whole book, but I’m not holding my breath.

The digital publishing world is more obsessed with restricting access than giving users the best possible reading experience.

And until that changes, which it won’t, if you want to make sure that your book is Kobo-compatible, relying on epubcheck is unfortunately not enough. Gotta chuck it into Adobe’s woodchipper first.

Either it will work, or it will fail silently. In which case, you probably used some forbidden new-fangled CSS.

Anyway, just throwing this out there as a post-mortem, in case anyone else is stumbling over it.

EPUB is an amazing open standard for ebooks, and yet so many implementations of it are just fundamentally flawed, all in the name of keeping IP lawyers happy.