Everything about the process went pretty smoothly until we tried to upload the book for sale via Apple’s iTunes Producer. The book popped into review and then out again with a validation error:
This was particularly odd to us because Apple’s validator is said to be based on a public validation tool that had already ok’d the same file:
iTunes Producer ERROR ITMS-9000 calibre_bookmarks.txt
The search above did a nice job, bringing up several threads on the mobileread.com site that serves as the Calibre support forum. The discussions are old, though, and it took quite a while to piece together the whole story. Let me just cut to the chase for you here.
After we first used Calibre to convert our manuscript file from a docx to an epub, we opened up the ebook in the Calibre Ebook Viewer (aka ‘the reader’). Who wouldn’t want to make sure everything looks good before publishing?
But, by default, the reader supports user-added bookmarks. It does this by inserting an extra file, calibre_bookmarks.txt, into the epub file set* the first time it opens the ebook. But it does NOT add that file to the epub’s internal manifest file. Apple’s version of the validator considers the un-manifested file to be a stowaway and potential malware. It rejects the epub accordingly.
*If you’ve never looked under the hood of an epub file, the paragraph above may make no sense to you. An epub is a single file, after all, not a set of files. In reality, though, it is both. The single epub file is actually a zipped archive of files. You can unzip it and look inside using any standard zip utility. Here’s what the inside of the Calibre Quick Start Guide looks like when unzipped (and after that pesky bookmarks file has been added):
You can avoid the ITMS-9000 error forevermore by simply turning off the bookmarking feature of the reader.
But don’t go looking for a button or checkbox labeled “Turn off bookmarks” or “Disable bookmarking” or anything like that. Nope, that would be a bit too simple. What you have to do, from the reader screen, is poke the Preferences jig on the left hand side.
On Configure Ebook Viewer screen, open the Miscellaneous options on the General tab, and uncheck Remember the current page when quitting. Then, click OK, to save the new setting.
So, how do you fix an epub that has already failed validation?
If you’re adventurous and the sort who likes to tinker around inside your file system, you can actually unzip* the epub, delete the stowaway file, and rezip the fileset. That’s what I did, just to see what would happen. I expected to get slammed for it by the iBooks validator. After all, this time the fileset really had been tampered with, right? But the resulting epub sailed through validation.
* Your mileage may vary with this trick. I’ve seen my Windows machines consistently be able to unzip and rezip epubs successfully. And Bret and I have seen it work on our Macs. But we’ve also seen the Mac unzip utility take the zip file and spit out a cpzg file, which then unpacks, very unhelpfully, back to a zip. This indicates the utility believes the archive is corrupted. If this happens to you, see this post at OsXDaily for the workaround.
If farbling with zip innards is not your idea of a good time, then, after you’ve disabled the bookmarking as described above, just:
- remove your converted ebook from the Calibre library
- add your original file — mine was a docx — back in
- reconvert using the same conversion options as before
The old book and the new are not associated by Calibre in any way, despite having the same name. Bob’s your uncle, the new epub will be clean and ready for upload. And do, by all means, feel free to preview it first!