Your EPUB is fine — Kobo says otherwise, and Adobe is to blame

A valid EPUB file was rejected as "corrupted" by Kobo e-readers, and the trail leads to a rendering engine Adobe wrote around 2010 and never modernised. The author, who publishes DRM-free ebooks, set out the case in a post-mortem after a reader reported that a new book would not open on any of their Kobo devices, across several hardware generations.

The file was not sloppy work. It passed epubcheck 3.3, the reference validator for the EPUB standard, and opened without complaint on Amazon Kindle, Apple Books and the desktop reader Thorium. A second build following the older EPUB2 rules also failed on Kobo.

One line of CSS

The break in the case came when the author disabled the book's stylesheet and the title suddenly loaded. Narrowing the sheet down, a single declaration turned out to be responsible: .copyright img { max-width: min(150px, 30vw); } — valid CSS Level 4. Rewriting it as the older max-width: 150px made Adobe Digital Editions open the file normally. Kobo's readers use RMSDK, the Reader Mobile Software Development Kit — Adobe's proprietary engine and the core of Adobe Digital Editions. Built for EPUB2 and only lightly updated for EPUB3, its CSS parser is effectively frozen around 2013: no flexbox, no grid, no math functions, no custom properties, and silent failure on anything it does not recognise. Adobe Digital Editions gave no error at all, the author notes; the only reaction was a white screen.

Two renderers, decided by file extension

An update to the post adds that Kobo actually ships two rendering paths. Standard EPUB files are routed to Adobe's RMSDK, while KEPUB — Kobo's own format — runs on a WebKit-based renderer that is actively maintained. Which one you get is decided by the file extension alone: renaming a book to ".kepub.epub" switches it to the WebKit engine, according to the KoWiki documentation the author cites.

Why epubcheck cannot catch it

epubcheck does check CSS, but it validates the file against the specification, not against a particular renderer's limits, so a book can be fully compliant and still die on a device. Commenters on Hacker News pushed the failure further back: CSS has required parsers to silently ignore declarations they do not understand since 1996, so the problem is not modernity but missing basics. For anyone hitting the same wall, the author points to a third-party tool that scans a stylesheet for rules that break on Kobo and fixes them automatically. The book has since been republished in a corrected version.