This resource page explains what EPUBCheck is, why it’s important, and offers guidance on how to address various EPUBCheck errors and warnings.
While EPUBCheck’s arcane-sounding error messages might seem intimidating and overly technical, most issues are actually rather easy to correct once you identify the specific problem.
As always, should you require any assistance, don’t hesitate to contact our support team via the Support link at the bottom of this page.
What is EPUBCheck?
EPUBCheck is a tool that analyzes your EPUB file to determine if it adheres to the EPUB format standard. The standard, as well the EPUBCheck tool itself, is managed by the World Wide Web Consortium, the international standards setting body for all things Internet. EPUB is the most common ebook file type used by ebook retailers and libraries.
Why do I care what EPUBCheck thinks about my ebook?
An ebook that fails EPUBCheck may not function properly across various e-reading devices. Most ebook retailers and library ebook platforms require that your ebook file pass EPUBCheck before they will allow your ebook into their stores. Smashwords therefore requires that your book pass EPUBCheck as a condition for distribution.
Is EPUBCheck compliance required if I only sell in the Smashwords Store?
EPUBCheck compliance is not a requirement for selling in the Smashwords Store. However, if a book is failing EPUBCheck and a customer complains that your book isn’t functioning properly, Smashwords may issue a refund to the customer and remove your book from sale.
My EPUB file looks fine, so why is it failing EPUBCheck?
EPUBCheck validates the underlying coding of the EPUB file to confirm it adheres to industry standards. A beautifully designed ebook can look great on the surface but still fail EPUBCheck. The moment you upload your ebook to Smashwords, we’ll automatically verify EPUBCheck compliance and report the results back to you in your Dashboard.
I’m uploading an EPUB created with a popular ebook design tool such as Adobe InDesign, Vellum, or Calibre. Any tips?
If you hired a professional ebook designer to create your EPUB file, they probably already checked your file for EPUBCheck compliance. If you’d like to validate compliance prior to upload, you can use a program like Pagina.
At Smashwords, you have the ability to upload your ebook either as a custom EPUB file, or as a Microsoft Word document. Most EPUBCheck errors we see originate from books that used a custom ebook design program.
Due to the number of different EPUB creation tools, each with their own quirks and limitations, we can offer only limited assistance in correcting EPUBCheck and formatting errors in custom EPUBs. We recommend referring to the documentation of the program you used to create your EPUB as a starting point to correct the issues with your EPUB. Or, if you hired an ebook designer to create this file, please share the EPUBCheck error messages with them so they can repair the file for you.
For additional information about managing custom EPUB files, or the unique EPUBCheck policies of different retailers, visit our Smashwords Direct resource page.
I’m not a technically inclined person. HELP!
If you find the EPUBCheck error messages difficult to understand, you’re not alone: don’t feel intimidated. If, after reading through this resource page, you find yourself confused or frustrated, please contact our support team. If you’re unable to repair the issue, you may wish to hire a low-cost freelance formatter from Mark’s List or elsewhere.
After upload, on your Dashboard, under the Premium Status column, click ‘Review EPUBCheck results’, which will take you to a page that reports the EPUBCheck errors your book is currently receiving. On the next page, click the folder icon to see the error details.
Most authors at Smashwords prefer to upload their manuscripts as Microsoft Word files. Here are some of the most common post-conversion errors seen by users of Microsoft Word:
• Error while parsing file: Duplicate 'Frame' - This error message indicates the presence of text boxes or tables (tables made of text, not images) that were not removed from the manuscript prior to upload as they should have been. A common culprit is the presence of headers and footers in Microsoft Word, which often render as text boxes in Word documents. Remove any such tables or headers and footers prior to uploading your Word .doc.
• Error while parsing file: attribute "width" not allowed here; followed by a list of various expected attributes - As above, this error message indicates the presence of tables or text boxes that were not removed prior to upload as they should have been. A common culprit is the presence of headers and footers, which often contain text rendered within text boxes. Be sure to remove any such tables or text boxes prior to uploading your Word .doc.
• Error while parsing file: attribute "start" not allowed here; followed by a list of various expected attributes - This indicates use of Word's automatic numbered and/or bulleted list feature. Instead of using auto-numbered/bulleted lists, you can avoid this error by defining and assigning a custom paragraph style with desired indentation and margins. Further information about managing paragraph styles can be found in Step 7 of the Style Guide.
• Error while parsing file: element "span" not allowed here; followed by a list of expected elements or element end-tags - This error indicates inconsistently applied paragraph styles. Please ensure that your paragraph styles are consistently and appropriately defined and applied throughout your text, as outlined in Step 7 of the Style Guide.
If the tips above don’t help you identify and solve your EPUBCheck errors, most authors will find the solution with one of the following methods. The first solution, the Nuclear Method, is something you yourself can do. The second option involves hiring a low-cost professional.
In cases where you’re unable to pinpoint the root causes in your Microsoft Word document of your EPUBCheck error, the “Nuclear Method,” as outlined in Step 5 of the Style Guide, will help you purge all corruption and create a clean file.
The Nuclear Method is, as the name implies, the formatting equivalent of pressing the Big Red Button to remove all formatting to purge hidden corruption in the file. A common cause of hidden corruption is when a Word file is edited and saved on different computers, operating systems, or word processors, or when the author or editor introduces non-standard formatting. The Smashwords Style Guide shares professional best practices that will help you format and style your book without errors.
The Nuclear Method is the surest method of creating a “clean” file. The downside, of course, is that the Nuclear Method will purge all your formatting (indents, font styles, and sizes) which means you’ll need to reformat your book according to the Style Guide once more. Use the Nuclear Method when the less intrusive methods described above are unable to correct EPUBCheck errors.
Many authors will often start their formatting adventure with the Nuclear Method so they can proactively purge any hidden corruption or poor styling that might cause EPUBCheck errors. We think this is a great strategy if you want to create the cleanest possible file.
At Smashwords, we’ve designed our tools and resources so that authors and publishers who desire to do things themselves at no cost are able to do so. But we also understand that many would prefer to hire a professional. If this matches your preference, you’ll find a great list of low-cost ebook formatters on Mark’s List. We publish this list of formatters as a public service; we don’t earn anything if you hire them. Nearly all of the formatters on Smashwords are Smashwords authors too, and these list members have formatted thousands of ebooks that achieve Premium Catalog approval on the first upload.