epubcheck 103: Reading errors
In Part 1 we looked at why Epubcheck is important. In Part 2 we looked at the various ways to use it. Here in Part 3 we’ll look at how to interpret the error messages and some common techniques to use if you have no clue what it’s saying.
What does an Epubcheck error look like?
In the following examples I’ve created a simple EPUB with one error—a missing closing tag for a paragraph. That’s see what happens when I run that through epubcheck.
The most basic error message—one that comes directly from the epubcheck program, looks like this:
ERROR: /Users/derrickschultz/Downloads/failedepub.epub/OEBPS/chapter0.xhtml(12,4): element "p" not allowed here; expected the element end-tag, text or element "a", "abbr", "area", "audio", "b", "bdi", "bdo", "br", "button", "canvas", "cite", "code", "command", "datalist", "del", "dfn", "em", "embed", "epub:switch", "i", "iframe", "img", "input", "ins", "kbd", "keygen", "label", "map", "mark", "meter", "ns1:math", "ns2:svg", "object", "output", "progress", "q", "ruby", "s", "samp", "script", "select", "small", "span", "strong", "sub", "sup", "textarea", "time", "u", "var", "video" or "wbr" (with xmlns:ns1="http://www.w3.org/1998/Math/MathML" xmlns:ns2="http://www.w3.org/2000/svg")
ERROR: /Users/derrickschultz/Downloads/failedepub.epub/OEBPS/chapter0.xhtml(13,3): The element type "p" must be terminated by the matching end-tag "</p>".
ERROR: /Users/derrickschultz/Downloads/failedepub.epub/OEBPS/chapter0.xhtml: The element type "p" must be terminated by the matching end-tag "</p>".
If you use the IDPF’s online tool, the error message is a little clearer. 
And FlightDeck’s tool makes it even clearer. 
Breaking Down an Error Message
Let’s break down the original epubcheck message. If you use FlightDeck and the online tool you’ll be in a better position to read these messages, but its never a bad idea to be able to interpret the original errors.
So it obviously starts with ERROR 😉
The second part of the error message defines the file path: /Users/derrickschultz/Downloads/failedepub.epub/OEBPS/chapter0.xhtml
That’s the full path to the file causing the error. If I were to look in finder it would be easy enough to find the file:
The next part will be two numbers inside parenthesis: (12,4). These two lines correspond to the specific cursor location within the file where the error is occurring (Sometimes this won’t appear if epubcheck can‘t determine the location of the error). In the example (12,4) this refers to the 12th line of the file, and the 4th cursor position. If I open that file in a text editor I can see exactly where that is:
The final part of the error message is the actual error: The element type "p" must be terminated by the matching end-tag "</p>". This particular error makes sense, but a lot of times these errors don’t look like they were meant for a human to read. But now you at least know how to interpret the error.
In the final part of this series, I’ll explain my process in actually fixing these errors, and provide a helpful “Order of Operations” when you run into confusing error messages.