All Collections
Author Help
Troubleshooting Book Preview Generation Failure with Line-Numbered Error Reports
Troubleshooting Book Preview Generation Failure with Line-Numbered Error Reports

Keywords: fix, fail, failure, book generation failure, preview failure, PDF failure, error, report, fix, troubleshoot

Leanpub Support avatar
Written by Leanpub Support
Updated over a week ago

Sometimes - hopefully very rarely! - when you hit the button to create a preview of a Leanpub book, you may get a notification that the preview process failed.

In this article we'll show you how you can use Leanpub's line-numbered error reports to try and track down the cause of the failure and fix it quickly.

If you haven't created a preview yet, please see this article to learn how:

From the AI Services Homepage Essay: "[W]e’ve also greatly improved Markua 0.30 error handling, including providing line numbers of errors if they occur. This will save our authors tons of time and will help us as well if anything goes wrong creating a Markua 0.30 book or course."

What Happens When Book Preview Generations Succeeds

When you're working on a Leanpub book, you'll occasionally want to run a "preview" of the book. This generates ebook files just for you.

Previewing a book is important for seeing what your book looks like and for distributing drafts to people to read.

However, on Leanpub previews are especially important because we encourage authors to publish their books as they go, chapter-by-chapter.

A preview lets you update your book privately, until you're ready to click the button to actually publish a new version of the book.

Here's gif of the normal preview process, showing the blue progress bar at the top of the page, that turns green when the process completes successfully:


What Happens When Book Preview Generations Fails :(

Occasionally, book preview generation fails.

Here's a gif of what that looks like, with the red error message at the top of the page showing which step failed:


Here's a static screenshot with the error message:

Why Does the Book Generation Process Sometimes Fail?

When you're writing your book in plain text, you can do anything you want in the manuscript text files, and add any "resource" files you want to (like images), which is of course a good thing!

But this total freedom also means you can do things that unintentionally cause the book generation process to fail.

This usually involves a "mistake" in your markup formatting. We're putting "mistake" in quotation marks because it's our job to make Markua simple enough, and we teach you how to use it well enough, that we regard every "mistake" as our own in a sense.

What to do When the Book Preview Process Fails

There are a few things you can do when the book preview process fails.

We'll explain them in order below. Following these steps in order is important for fixing the issue as quickly as possible, with the least frustration.

1. Check Your Recent Changes

Review any recent changes you've made to your manuscript for something that looks funny. If you were trying something new in Markua, like adding an index entry for the first time, that may be causing the problem.

Try undoing the change to see if the preview process works then.

We recommend this first because it may be really obvious on a quick review of recent changes what the problem might be.

2. Check Your Email for the Generation Failure Email

If quickly checking your recent changes doesn't solve the problem, check your email. (Just to be clear, we use the email address for your Leanpub account.)

You should have a generation failure email from Leanpub with the subject line:

"[Leanpub] There was a failure while generating your book [YOUR BOOK TITLE]"

The email will look something like this:

The "Warning" section with the error description (or descriptions, if there's more than one) will start after a short explanation at the top:

Let's zoom in on the first warning:

There are five elements here to look look for and examine.

First, the warning will show the name of the file where you can find the error. In this case, the file name is Writing in Markua:

Second, it will name the line in the named file where the error can be found. In this case, it's line 57:

Third, it will actually show you the text of the manuscript that is in that file and at that line:

Fourth, the line with the error will be set out with a >:

Here's the line itself:

> 57 ![Palm Trees](palm-trees.jpg)

So, we know the issue is somehow being caused by an attempt to insert an image into the book, in this case the image file palm-trees.jpg.

Fifth, the warning will actually attempt to explain the cause of the issue explicitly:

In this example, the warning says:

[WARNING] The resource resources/palm-trees.jpg is not stored locally.

So, the issue here is that the palm-trees.jpg file appears to be missing!

3. Open the Named Text File and Find the Line with the Error

Now that you know the name of the file with the error and the line number to look for, you can go to your manuscript and check what's happening.

In this example, we're using a demo book created in Leanpub's Browser writing mode.

Here's the full tutorial for that writing mode:

Getting Started Writing a Book in Leanpub's Web Browser Writing Mode

(If you've chosen a different writing mode, such as our GitHub writing mode or our Dropbox writing mode, the process will look different of course, but the steps will essentially be the same as those shown here.)

Here's a screenshot of the Write tab for the book:

We're looking for the file named Writing in Markua, which you can select at the top left, in the list of Manuscript files:

Here's what that file looks like when we select it:

Now, we know we're looking for line 57, and we know what the line looks like, so let's scroll down until we see it:

Nothing appears to be wrong with the Markua for in this example. This is how you insert an image with a caption:


Now, we know the warning said:

[WARNING] The resource resources/palm-trees.jpg is not stored locally.

So, let's click on the Resources folder in the Write tab:

Here's what the book's Resources folder looks like:

We can see the list of files does not include palm-trees.jpg:

So, let's add that file:

(We recently improved how you upload files; we'll make a separate article in this Help Center about that, and update the article on how to add images to a book in the Browser writing mode.)

Here's a screenshot showing the Resources folder with the new uploaded image listed:

Now that we think we've fixed the problem, let's go back to the Preview page like we did before, and trying creating a preview again:

Success, we added the missing image, and the preview worked!

What to Do if You Need Help

If you follow these steps and you still can't figure out what's causing the problem, there are three steps you can try next.

1. Post About the Issue on the Leanpub Authors Forum

Your fellow authors may be able to help! Post as many details about the issue as you're comfortable sharing on the Authors Forum here:

The Leanpub Authors Forum

2. Search the Authors Forum and the Help Center for Similar Issues

In addition to searching the Authors Forum for reports of similar issues, you can also search our Help Center:

The Leanpub Help Center

A few years ago, we adopted a policy of turning all our interactions with authors into generic articles on whatever the issue was, so there are lots of articles with solutions in the Help Center!

3. Ask the Leanpub Team for Help

While it's best to try to get an instant answer in the Authors Forum or the Help Center, you can also reach out to the team at for help.

If you do this, please make sure to share as many details of the issue as possible.

To get to a solution as quickly and efficiently as possible, here are some steps we highly recommend you follow:

- Email the team from your Leanpub email address, so we know it's actually you!

- Write an expressive subject line, for example "Preview generation for my book is failing on Step 16"

- Include a link to your book in the email (this really helps)

- Name the file in the book that you think may be causing the issue, if you have an idea of which file it might be (for example, a file you changed recently)

- Attach the text file to the email if you're comfortable doing that, or share a snippet of the text file in the email itself

- Finally, share a screenshot or screenshot of any details that you think are relevant. Sharing screenshots of issues is the number one time saver in our experience!

If you have any feedback or questions about this article, please email the Leanpub team about it at!

If you have any questions or thoughts on writing and self-publishing with Leanpub, please join our global community of authors in our Authors Forum here!

Are you interested in self-publishing, and creating your first Leanpub book? Here are some quick tutorials for our most popular writing modes:

Are you looking for great deals on Leanpub ebooks, ebook bundles, and courses? Sign up for our Weekly and Monthly newsletter sales here!

Subscribe to our YouTube channel here:

Please subscribe to our YouTube channel here:

You can also follow Leanpub in lots of other places!

Did this answer your question?