Help › Validation codes

Validation codes

Your file is checked when you upload it. Findings have a code, a line number, a message and a suggestion.

• E codes are errors. The upload is refused until you fix them.
• W codes are warnings. The book is still made, and the warnings are shown on the progress page.
• I codes are notes. They tell you what was decided for you.

Errors

E001 File is empty

The file has no content, or only blank lines. Add your text and upload again.

E002 File is not valid UTF-8 text

The file is saved in another encoding, or contains binary data. Open it in your editor and save it as UTF-8. In most editors this is under Save as or Encoding.

E003 No Markdown file in the upload

The upload has no file ending in .md (or the zip has none). Add your Markdown files, either at the top level of the zip or together in one folder.

E004 The zip cannot be used

The zip is damaged, encrypted, too large when unpacked, or contains an unsafe path or a link. Create the zip again from your folder without links, and keep it within the size limit.

E005 Code block never closed

A line with three backticks (or three tildes) opened a code block, and no matching line closed it. Everything after it would become code. The finding shows the line where the block opened.

Fix: add a closing line of three backticks after the code.

```python
print("hello")
```

E006 Book is over the limit

PDF books are limited by page count, and the other formats by word count. The limits are on the limits page. Split the book into parts. This error appears on the progress page after conversion, not at upload.

E007 A conversion tool failed

Pandoc or Typst failed or took too long. Check the message on the progress page. Very large tables, or extremely long lines of code, are the usual cause. If it keeps happening with a normal file, contact us.

E008 Front matter never closed

The file starts with --- on line 1, which opens a front matter block, but no second --- line closes it.

---
title: My Book
author: Me
---

Close the block, or delete the opening line if you did not mean to write front matter.

E009 Front matter but no content

After the front matter there is no text. Add your chapters below it.

E010 Image not found

An image with an https:// link could not be downloaded when the book was built, so no book was made. The message names the link, the line, and the reason, for example the server says the image does not exist (404) or access was refused. Every image that failed is listed.

Images in a zip are checked at upload: an image path that is not in the zip (or has different capital letters) is also reported here, with the file name and line. Capital letters matter, so Images/A.PNG is not images/a.png.

Fix: open the link in a private browser window. If it does not show the image there, MarkdownBooks cannot load it either. The image must be public and a PNG, JPEG, GIF or WebP file under 10 MB. Both Markdown images and <img> tags are downloaded:

![Architecture diagram](https://example.com/diagram.png)

<img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/0fc8d24e-3bf2-4631-8d1f-6bf4513bb5e3" />

Links to private networks, such as localhost or internal addresses, are refused. A book can have up to 100 images.

E011 File name has no number

When you upload several Markdown files, each name must start with a number (followed by -, _, or .), so the order is clear: 01-intro.md, 1.intro.md, 02-setup.md, 03-usage.md. Files are joined in order of that number. The message names the file that needs renaming.

E012 Two files share a number

Two files start with the same number, for example 01-a.md and 01-b.md, so their order is unclear. Give each its own number.

E013 Markdown files in different folders

The .md files are in more than one folder. Put them all in one folder. Images can stay in any folder.

E014 File type not accepted

You can upload .md files, or one .zip, not both together. Put everything in the zip, or upload only the Markdown files. Other file types (for example .docx or .txt) are not accepted.

Warnings

W101 Image not included

The image could not be included, so it is replaced by its alt text. This happens for relative paths such as images/a.png (only one Markdown file is uploaded, so the file cannot be found) and for data: images. Use a public https:// link instead, and the image is downloaded and placed in your book. Write alt text that describes the image either way:

![A red door at the end of a corridor](door.png)

W102 Heading level skipped

A heading jumps more than one level, for example # followed by ###. Use ## in between, or change the level.

W103 Link to a missing heading

A link such as [see](#setup) points to a heading that is not in the file. The target is the heading text in lower case, with spaces turned into dashes: ## Set up is #set-up.

W104 Table row has the wrong number of columns

A row has more or fewer cells than the header. Add or remove cells so every row matches.

W105 No headings

The file has no # headings, so the whole book is one chapter and there is no contents page. Add a # heading for each chapter.

W106 Repeated heading

Two headings have the same text. The second is renamed automatically, so links to it may not go where you expect. Give each heading its own title.

W107 Raw HTML removed

The file contains HTML tags such as <div> or <b>. They are not supported and are removed. Use Markdown instead: **bold** rather than <b>bold</b>. HTML comments are allowed.

W108 Heading has no text

A line has # marks and nothing after them. Add a title or delete the line.

Notes

W109 Front matter in a later file is ignored

Only the first file's front matter (title, author, date) is used. A later file has its own front matter block, which is skipped. Remove it from that file.

I201 Title taken from the file name

There is no title in the front matter and no # heading. The file name was used. Add a title in the front matter to control it.

I202 Text before the first heading

Text before the first heading is used as an introduction at the start of the book.

Something unclear? Tell us and we will improve this guide.