Why your EPUB is being rejected from Apple Books Store

It has become quite unlikely to submit anything to Apple without getting rejected at the first few attempts. Even ebooks.

Apple. Rejections. A very unfortunate combination. While the most common reaction to those long-awaited rejections would be to flip your keyboard into the air and punch the screen into the back wall, we would not advise that. There is a massive audience behind those over-protected Apple stores, very willing to pay for good products they find. Also, back wall maintenance may be expensive. So take a deep breath. Once you’re calm, let’s resolve the submission issues.

Validating your EPUB file

A great thing about ebook submissions, is that you do not have to rely on Apple’s vague ambiguous error messages. You can actually validate the EPUB file and find the problems yourself. Apple uses IDPF‘s EpubCheck tool to check for errors in the EPUB prior to submission (reference: https://support.apple.com/en-eg/HT202974). This tool is available independently at validator.idpf.org. Simply open this page, choose your EPUB file, and click Validate. After a while, you will be given a list of all the errors and warnings existing in your EPUB. You can ignore the warnings, since they do not break submissions to Apple. The free online validator accepts files up to 10MB in size.

What if my EPUB is larger than 10MB?

Fair enough. In this case, you will need to download EpubCheck and run it locally.

Requirements:

1. Java installed on your machine
2. Downloading the EpubCheck source files from their GitHub page

Steps

1. Extract the downloaded EpubCheck source files anywhere on your computer
2. You will find a file epubcheck.jar along with a number of files and folders. Copy and paste your EPUB file into the same directory
3. Open your command line window / terminal:
   On Windows, by holding shift and right-clicking inside the folder and choosing Open command window here
   On Mac, by Cmd-clicking on the folder and choosing New Terminal at Folder
4. Type in the following command, replacing epubfilename.epub with your own filename

java -jar epubcheck.jar -out report.xml epubfilename.epub

You will find a full report for all the errors and warnings in the file named report.xml. Each error/warning will have a description, accompanied with the file in question and location (line number).

Most common errors

As an ebook publishing technology provider, we have come across many types of errors. But we have found a particular set to be common among most users. If you are unfamiliar of the anatomy of an EPUB file, read our blog article: Alice in EPUB-Land. Once you’re able to open and edit the EPUB file contents yourself, as well as package it back again, it will be simple to fix all these problems.

Here is the list of errors we found to be most common, along with their suggested fix:

Mimetype must be the first file

File order matters inside zip archives. The mimetype must be the first file. This is a bit tricky. On Windows, to accomplish this, select all the files you would like to zip, and then (here’s the trick) right-click on the mimetype file, and choose Send to > Compressed (zipped) folder.

Unsupported tags

Any tags or attributes you make up, will not work, as they need to follow the EPUB standard. For example, we used a “content” attribute, to define some interactive behaviour. That failed. But once we replaced it with “data-content”, that worked like a charm.

IDs must start with a letter

Every item in the manifest must have a unique ID, starting with a letter, not a digit.

Item properties

Check the properties you assign for each item in the manifest. If you have a chapter (HTML page) which is using any type of Javascript, then you must assign the “scripted” property to the item. If you are using remote resources (e.g. images or videos residing on public websites) then assign “remote-resources”.

Reference everything

Every little file you use must be included as an item in the manifest. Do not leave any files in your EPUB hanging loose.

Avoid empty identifiers

If you will include a certain identifier for the book, such as dc:description, you must enter something inside. Do not leave blank, otherwise it will give you an error.

Include last modified date

The manifest must include one and exactly one modified property, which specifies the last date/time the EPUB was modified. See:  http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-opf-metadata-identifiers-pid

Correct doctype

If you are targeting EPUB 3.0, then make sure you are using the HTML5 doctype declaration: <!DOCTYPE html>

Unsupported attributes

There are pretty standard attributes used today that may give you errors when validating using EpubCheck. For example, the width and height attributes for the img tag, will return an error if you use a percentage, or include the “px” at the end of the integer . Also watch out for deprecated attributes such as align, cell-spacing and cell-padding. They will all generate errors. Use CSS instead.

Unsupported CSS

Since we deal with many Arabic ebooks and users, it has come to our attention that EPUB does not support the CSS “direction” property. Instead, the EPUB standard encourages usage of the HTML “dir” attribute.

Hidden characters

This is the ugliest kind of errors you will get. You will get an error saying that one of your files contains unsupported characters. Open this file in Notepad++ and go to View  > Show Symbol > Show All Characters. This will reveal that son of a glitch.

Extra-large images

If you use images straight out of your super-high-megapixel camera, expect your submission to be rejected. Your images must contain a maximum of 4 million pixels. Sometimes you’ll find yourself doing some Math, to find the largest dimensions you could use for a particular image.

For references, and a full list of possible EPUB validation errors, click on the following link: epubzone.org/news/epub-3-validation

Conclusion

EPUB is an evolving standard, and the IDPF has reason to place all these rules, mainly to maintain consistency across all readers and devices. Luckily, their EPUB validation tool (EpubCheck) can let you validate your EPUB file locally, before submitting to online stores.  Investing the time to learn how to use that tool, will save you a lot of time later. Let us know if you’ve repeatedly come across any common errors not listed above.

Read more.

iBooks Author vs. Kotobee Author

The Basic Guide to Self-Publishing Ebooks

Turn Your Book into an Ebook App in Minutes