Bookmate previously published an article " How to quickly and non-destructively repair EPUB format e-book files that failed to push ". The repair method provided in the article can solve most of the problems that Amazon system bounces after pushing EPUB files. However, this method cannot cover all problems. As the small partners continue to provide sample files to the book companion, more problems related to pushing EPUB files have emerged.
This article summarizes some representative problems based on the sample files provided by the partners, and provides corresponding solutions for each problem. These problems are divided into two categories, namely " problems that cause push failures " and " problems that cause incorrect content ". The former mainly solves the problem of unreachable push, and the latter mainly solves the problem of readability problems even though the content is pushed successfully.
This article will use the software Sigil , if other software (such as Caliber) has equivalent functions, it can also be used as a substitute.
1. The problem that caused the push failure
Push failure refers to the failure to successfully push the EPUB file to Kindle, usually you will receive a bounce letter from Amazon titled "There is a problem with the document you sent to Kindle", and the content does not provide a solution to the problem except for a list of supported formats. Valuable information.
An EPUB file may have the following problems at the same time, you can check and fix them one by one when the push fails.
1. Some files in the EPUB do not meet the specification
Amazon's Personal Document Service has a strong fault-tolerant mechanism for pushed EPUB files. Even if some content does not conform to the EPUB specification, it can be processed normally under normal circumstances, but only for EPUB 2.0 navigation control files toc.ncx and EPUB 3.0 The navigation document nav.xhtml is more sensitive. If there are "errors" in these two files, there is a high probability that the push will fail.
This is the most common issue causing EPUB push failures, and the first to try to fix. The specific solution is as follows:
Open the EPUB file with Sigil, and click the menu [ Tools → Table Of Contents → Generate Table Of Contents... ] (or press the shortcut key, [Ctrl + T] for Windows, [ Ctrl + T ] for macOS) Command + T ]. However, it should be noted that this method may destroy the directory hierarchy.
Finally, click the floppy disk icon button in the upper left corner (or press the shortcut key, Windows is [ Ctrl + S ], macOS is [ Command + S ]) to save the modified file.
For a detailed explanation of this problem, please refer to the article " How to quickly and non-destructively repair the EPUB format e-book file that failed to be pushed ".
2. The HTML file name contains spaces and Chinese characters
If the EPUB file is inserted into the advertisement page, and the file name contains spaces and Chinese characters, the push will also fail. The solution is to open the EPUB file with Sigil, directly delete the HTML page with spaces and Chinese characters and save it.
3. The body tag in the HTML file contains an ID
In the toc.ncx file of the EPUB file <content>
, src
the HTML file path pointed to by the attribute value of some elements contains URL fragments, that is, similar to #test_1 in the path text/part0000.html#test_1. If the corresponding id
attribute <body>
on the element, it may will cause the push to fail. The solution is <body>
to id
move the corresponding value on the element to its child element, or directly delete the fragment part of the path (that is #
, and the following characters).
Finally, click the floppy disk icon button in the upper left corner (or press the shortcut key, Windows is [ Ctrl + S ], macOS is [ Command + S ]) to save the modified file.
4. The language element in the OPF file is wrong
Open the EPUB file with Sigil, check its OPF file (usually the file name content.opf) metadata <language>
element , if the element is missing, or its content part does not specify a language code, or specifies the wrong code (see below) will cause the push to fail.
<dc:language>und</dc:language>
The solution is to use Sigil to edit the OPF file. If <language>
the element , <metadata>
add the code shown below in the element. Note that the actual language code shall prevail. If the language code in <language>
the element is wrong, change it to a valid language code, such as Chinese zh
or English en
. For more information, please refer to the ISO 639-1 language code list.
<dc:language>zh</dc:language>
You can also add or modify language elements through Sigil's menus. First click [Tools → Metadata Editor...] to call out the metadata editing interface. If <language>
the element , click the [ Add Metadata ] button, select " Language (Language) ", click the [OK] button and then select " Chinese - China (Chinese - China) ", click [OK] twice button to complete the addition. Be careful not to add repeatedly.
If the language code in <language>
the element is incorrect, double-click the corresponding field of " Value " of " Language" , select " Chinese - China ", and click the [OK] button to complete the modification.
Finally, click the floppy disk icon button in the upper left corner (or press the shortcut key, Windows is [ Ctrl + S ], macOS is [ Command + S ]) to save the modified file.
5. Duplicate item elements appear in the OPF file
If <item>
the elements are repeated, the push will fail, and the push can be successful after removing those elements. Sigil does not seem to have a tool to detect this problem. You can try to use KindleGen to convert the problematic EPUB file. If there are duplicate item elements, the software will prompt you which one is duplicated. The prompt information is as follows:
Error(xmlmake):E27012: Item or process id already used: 180630.jpg
6. The number of hidden characters in CSS exceeds the limit
Kindle e-books have restrictions on the use display:none;
of , and the characters in the hidden content block cannot exceed 10,000, otherwise the push will fail. Therefore, it is recommended to remove all display:none;
declarations .
2. Problems that lead to content errors
Sometimes even if the EPUB file is successfully pushed, its content still has readability problems, such as garbled characters, wrong directory hierarchy, etc.
1. Garbled characters appear in the content of the e-book
The general manifestation of garbled characters in the pushed e-books is that all Chinese e-books are garbled, and some punctuation marks in English e-books are garbled. Generally, this is caused by the fact that the XHTML file in the EPUB file does not specify UTF8 encoding.
The solution is: download and install the EPUB editor Sigil , then use Sigil to open the EPUB file, and click the menu [ Tools → HTML Reformat (Reformat HTML) → Improve all HTML files (Mend All HTML Files )]. Sigil will automatically patch all HTML files, save and push them at the end.
2. The directory hierarchy of the e-book is wrong
If the directory hierarchy of the e-book does not match your expectations, you can use Sigil's directory editing function [ Tools (tools) → Table of Contents (Table Of Contents) → Edit Table of Contents... (Edit Table Of Contents...) ] to adjust it.
- The title can be selected by pressing the up and down arrow keys on the keyboard (or by clicking on the mouse);
- Press and hold the Ctrl key plus the down arrow key to adjust the order of the titles (you can also click the up and down arrow buttons on the right side of the interface);
- Use the left and right arrow keys to adjust the indentation of the title (you can also click the left and right arrow buttons on the right side of the interface);
- After editing, click the [OK] button to save.
Finally, click the floppy disk icon button in the upper left corner (or press the shortcut key, Windows is [ Ctrl + S ], macOS is [ Command + S ]) to save the modified file.
3. The e-book navigation directory is missing
If after pushing the EPUB e-book to Kindle, you can't navigate to the directory through Kindle's "Go" function, it may be because the URI in the EPUB navigation file (usually toc.ncx) has a fragment (as shown below).
text/part0001.html#UGI0-1af7590487e04e47b91ab6bb431b89f3
Although this is correct in the EPUB specification, it is estimated that it is a quirk of the Amazon server that lost the navigation table of contents when converting the format. There are two workarounds, one is to delete the fragment in the URI, and the other is to regenerate the directory. The specific method is as follows:
The specific way to delete the URI fragment is to open the EPUB file with Sigil, double-click to open the file toc.ncx in the left column, and then enter the regular expression in the "Find" input box, leave the "Replace" input #[^"]*
box blank, and "Pattern" Select "Regular Expression" from the drop-down menu, and finally click the second button after the "Replace" input box to replace all and save.
Another way is to use Sigil's catalog generation tool to regenerate the catalog again. The specific method is to click the menu [Tools → Catalog → Generate Catalog] and save. Note that this method may change the directory hierarchy in some cases.
Due to the limited number of EPUB file samples, the above problems cannot cover all cases. If you still fail to push the EPUB file after repairing the EPUB file using the above methods , you can try to use the Sigil + EpubCheck plug-in to detect and repair content.opf and toc.ncx If there are any problems with a file, it can generally be pushed successfully.
In addition, you can also try to use the Caliber format conversion function, now convert the EPUB format to AZW3, and then convert to EPUB format, sometimes it can also solve the problem of push failure.
If you have better solutions or tips, please leave a message below this article to share.
©