Tuesday, July 6, 2010

Hyperlink with Ampersand Causes InDesign Export to EPUB to Fail

I've been working on a book about creating EPUB files using InDesign and other tools for about six months. Today I sent the final files to the printer—it should be in bookstores by the end of the month. Then I chose Export to EPUB and it failed. Just failed. No details, no clues. It did give me this lovely dialog box:
Cannot Export ePUB. Export Failed.-2
I had been converting RGB images to CMYK, so I thought maybe that was the culprit. I changed them all back. Nothing. Not only nothing, but each time I tried an export, the script would stay on the screen, requiring me to quit all the way out of InDesign.

I thought maybe a large PDF file at the end of the book was the trouble, but that didn't make sense since it had exported fine with it just two days ago. Thanks to suggestions from my Twitter friends, I restarted and repaired permissions.

I googled "InDesign EPUB Export Failed" but only got a few people with the same problem and no solutions.

I emailed a couple of InDesign gurus I know, including Teus de Jong, who has written a number of useful scripts for InDesign, including one that adds the otherwise missing required date and fixes the annoying bug that breaks hyperlinks and cross-references in exported EPUB files.

Teus wrote me back offering to look at my files with a debugger (since the dialog box was so vague), but it's 200Mb and seemed a lot to ask. So instead I asked if I could run the debugger myself.

No problem, he said. Open the OEBExportMenuItemLoader.jsx file, which is in the startup scripts folder, within the HTML for Digital Editions (or XHTML for Digital Editions) folder, inside your main InDesign program folder. (I just opened it with BBEdit.)

On line 31, he said, change var DEBUG = false; to var DEBUG = true;

Next time you try to export the EPUB, a DigitalEditionsExportLog.txt file will appear (on his PC it goes to My Documents, on my Mac it appeared in the Documents folder).

So, I followed his instructions, reexported the file, and lo and behold the DigitalEditionsExportLog.txt file appeared as promised. There was lots and lots of stuff about creating this style and that style, but at the very end, it said:

Error: XML error in line 474
- Not well-formed (invalid token)
Error Number: 60
File: undefined
Line: 794

Line 474? XML error? I puttered around InDesign's help files trying to see how to look at the XML representation of my file. Where would that be? I wrote Teus one more time hoping I wasn't bugging him too much and he told me that that probably referred to a temporary XHTML file created by the script.

I went back to the DigitalEditionsExportLog.txt and the last XHTML file referenced before the error was this:

Entry: OEBExporter.addChunk
temp file should be: /private/var/folders/xf/xfcWz+ZZGZKuQUR7NebUiU+++TI/TemporaryItems/onedoc_4/OEBPS/ePub-STTP-5.xhtml

I opened Terminal and copied in the whole path to the file, without the file name, followed by a return. (There must be an easier way to get to this location, but I confess I don't know what it is.)

Then I typed open ePub-STTP-5.xhtml.

The temporary ePub-STTP-5.xhtml file opened in BBEdit.

I scrolled down to line 474 and found this:

<div class="numbered-steps" xml:lang="en-us">
2 Download both KindleGen and the Kindle Previewer from <span class="link"><a href="http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621">Amazon’s site</a></span>.</div>

It turns out that the hyperlink that I created to Amazon's site contains an ampersand, and when InDesign tried to convert it to XML within the hyperlink, it didn't properly code the ampersand, and the resulting XML was badly-formed (a grand faux-pas in XML land). InDesign didn't know how to recover, and so stopped exporting the file. (If you're not sure what's causing the error, you could use a syntax checker to point out the error. In BBEdit, you'll find it at Markup > Check > Document Syntax)

I went back to my InDesign file, removed the hyperlink (I just put the URL in the text instead), and exported again, and it worked like a charm. I'll put the link in the EPUB by hand (properly coded!)

Moral of the story: Don't add hyperlinks with URLs that contain ampersands to an InDesign document if you intend to export the file to EPUB.

And second, if InDesign fails to export to EPUB, you have a number of tools at your disposal.

And thank you, thank you, Teus de Jong!


  1. Is the badly formed XML to do with the expectation of an entity code following the ampersand, or is this nothing to do with it?

  2. First, Thanks for writing this blog on epub, I seem to have found your blog the other day and I have reading your entries to catch up, today I read that you are authoring a book on ebpub.
    I can't believe my luck I have been looking everywhere for information, instead of the bits and pieces that is out there. I have been want to do work on producing ebooks and wanted to start my own company for ebooks.
    So sign me up for the book, are you selling them or are you selling them through a publisher? Can I pre-order the book.
    Can you email the information for the book, because I can't wait to start reading it.
    Matthew Priester

  3. Hi Matthew: You can preorder the book from Amazon, Barnes & Noble, or Peachpit (my publisher).

    The EPUB version should be available much sooner (early next week?), and in addition to those sites (and others), I will be selling it on my own site. I promise to announce that here as soon as I have a definite date.

  4. Liz, I am reading through all your notes on this blog.

    "Moral of the story: Don't add hyperlinks with URLs that contain ampersands to an InDesign document if you intend to export the file to EPUB." there is a way out for this.

    Replace ampersand with "%26" and see if it works. It should work :)

  5. Anthony, yes the badly-formed XML has everything to do with the ampersand, which cannot exist as a character by itself but must ALWAYS be entered as & amp ; (with spaces just in case Blogger wants to make it into a &).

    Vicky: I tried both & amp ; and %26 and InDesign doesn't choke, but iBooks gave me a weird error. Still, I'm not convinced the error is due to the &. Must test more. I'll report back.

  6. Actually, since epubs are XHTML Strict, any ampersand will cause it to fail. This is why most sites are done in XHTML Transitional, to allow some fudging on stuff like those ampersands. Validators will always mark ampersands as errors in the HTML when the doctype is transitional; strict will cause it to fail.

  7. I have watched a recent "How To" video by Terry White in my research to convert InDesign CS5 publications to epub—"Creating an iBook (ePUB) for the iPad with InDesign CS5". One interesting thing he said on the video was about hyperlinks and it would be good to include in your book about such bugs things (you might sneak it in as a sidebar): "The hyperlinks, you have to be concerned about how long they are." He says the link to his book on Amazon for example are extremely long and he received an error when exporting. He says to use a URL shortener like tinyurl.com or bitly to shorten them. After inputting them from shortening them he had no problem with it.

    I am very glad you are coming out with a book using for this using InDesign CS5 since even recent "how-to" information is explained using CS4. I actually have a client waiting for me to convert the magazine that I lay out and design twice a year and they want me to do the previous two issues. I can use all the info I can get my hands on at the moment. The last issue turned out to be in very high demand. Converting it to be available as an epublication should help get it out to the masses.

  8. Well, I look for an & in my links but there weren't any. Is there another reason for "failed"...Am also looking forward to your book.

  9. Thank you! I was beating my head against this problem, exporting to IDML, etc., and this was precisely the problem.

  10. Thank you for this article!
    You just saved me a lot of aggravation. I, too, was stumped by the lack of info in the error dialog box. I found the offending links with ampersands, removed them, and the export to ePub completed.

  11. Thank for this post. I don't know what I would have done otherwise.

  12. Thanks for posting this. As a side note, does Adobe post hotfix updates to correct problems like this?

    I am a Microsoft MVP and when someone in the community documents a bug such as you've done here, Microsoft will release a hotfix before the next service pack comes out.

    Is there an equivalant process at Adobe, or do they just expect people to shell out the money for InDesign CS5.5?

    I was convinced to upgrade to CS5 specifically for the ePub capabilities, but that is a complete joke. If it hadn't been for your book, I would not have been able to successfully create any ePubs. Thanks for helping to decode the process.

  13. THIS POST WAS A LIFESAVER. The ampersand thing was getting the best of me!

  14. Liz, thank you for writing this article. It has saved my day.

  15. To be honest: This isn't very surprising at all. Although most browsers happily accept hrefs with unescaped ampersands, this is simply no correct XML/(X)HTML. Just use &amp; instead and everything should work fine.


More of my books