Your EPUB Is Fine. Kobo Disagrees. Blame Adobe - André Klein Dot Net

Your EPUB Is Fine. Kobo Disagrees. Blame Adobe - André Klein Dot Net

"You shall not pass!"

[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 {<br>max-width: min(150px, 30vw);<br>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...