Appendix D: Application Messages

All warning, error, and failure messages emitted by the Asciidoctor CLI (i.e., asciidoctor) are listed in the table below. These messages are written to the console via stderr (i.e., standard error). Most messages also apply to the API, though keep in mind they’re written directly to stderr.

Placeholders
<docname>

represents the basename of the source file being processed (e.g., sample.adoc).

<file>

represents a path to the input file or other referenced file.

<uri>

represents a URI being referenced.

<x> or <y>

placeholders for other contextual information in the message.

Categories
ERROR

Errors do not stop conversion, but the output document will almost certainly be wrong.

FAILURE

Failures are fatal; no output document will be produced.

WARNING

Warnings do not stop conversion, but they indicate possible problems, and the output may not be what you were expecting.

List of Application Messages
Category Message Cause See also

ERROR

input file <file> missing or cannot be read

Check that the file exists and that the filename is not misspelled.

Using the Command Line Interface

ERROR

include file has illegal reference to ancestor of jail; recovering automatically

The safe mode is restricting access to an include file outside of the base directory.

Running Asciidoctor Securely

ERROR

input file and output file cannot be the same: <file>

Choose a different output directory or filename.

ERROR

partintro block can only be used when doctype is book and it's a child of a part section. Excluding block content.

Invalid book document structure.

Book Parts and Chapters

ERROR

unmatched macro: endif::<x>[]

endif::[] with no unclosed preceding ifdef::<x>[].

ifdef Directive

ERROR

<docname> dropping cell because it exceeds specified number of columns

Tables

ERROR

<docname> illegal block content outside of partintro block

Invalid book document structure.

Book Parts and Chapters

ERROR

<docname> invalid part, must have at least one section (e.g., chapter, appendix, etc.)

Invalid book document structure.

Book Parts and Chapters

ERROR

<docname> malformed manpage title

Invalid man page document structure.

Man Pages

ERROR

<docname> malformed name section body

Invalid man page document structure.

Man Pages

ERROR

<docname> maximum include depth of 64 exceeded

Does your file include itself, directly or indirectly?

ERROR

<docname> mismatched macro: endif::<x>[], expected endif::<y>[]

ifdef/endif blocks must be strictly nested.

ifdef Directive

ERROR

<docname> name section expected

Invalid man page document structure.

Man Pages

ERROR

<docname> name section title must be at level 1

Invalid man page document structure.

Man Pages

ERROR

<docname> only book doctypes can contain level 0 sections

Illegal use of a level-0 section when doctype is not book.

Sections

ERROR

<docname> table missing leading separator, recovering automatically

Check for missing cell separator characters at the start of the line.

Tables

FAILED

missing converter for backend '<x>'. Processing aborted. (RuntimeError)

You used -b with an invalid or missing backend.

FAILED

'tilt' could not be loaded

You must have the tilt gem installed (gem install tilt) to use custom backend templates

WARNING

abstract block cannot be used in a document without a title when doctype is book. Excluding block content.

Invalid book document structure.

Abstract

WARNING

cannot retrieve contents of <x> at URI: <uri> (allow-uri-read attribute not enabled)

Reading from a URI is only allowed in certain safe modes and the allow-uri-read attribute must be passed to the application.

Include Content from a URI

WARNING

could not retrieve contents of <x> at URI: <uri>

Web address not found.

WARNING

could not retrieve image data from URI: <uri>

Web address not found. Only occurs with allow-uri-read and data-uri. Check the URI.

Include Images by Full URL

WARNING

dropping line containing reference to missing attribute: <x>

An attribute cannot be resolved and the attribute-missing attribute is set to drop-line.

[catch-a-missing-or-undefined-attribute]

WARNING

file does not exist or cannot be read: <file>

You specified a stylesheet (-a stylesheet=<file>) but <file> does not exist or is not readable.

WARNING

gem 'thread_safe' is not installed. This gem is recommended when registering custom converters.

You have registered a custom converter, and you have not installed the thread_safe gem.

WARNING

gem 'thread_safe' is not installed. This gem is recommended when using custom backend templates.

You are using custom templates (-T <template_dir>), but you have not installed the thread_safe gem.

WARNING

image to embed not found or not readable: <file>

You used :data-uri: but the file could not be found.

Managing Images

WARNING

include file not readable: <file>

You do not have permission to access the file.

AsciiDoc vs non-AsciiDoc files

WARNING

input path <file> is a <x>, not a file

The path is not a file (perhaps it is a socket or a block device).

AsciiDoc vs non-AsciiDoc files

WARNING

optional gem 'asciimath' is not installed. Functionality disabled.

asciimath is one of the libraries used for equations.

Equations and Formulas

WARNING

optional gem 'coderay' is not installed. Functionality disabled.

CodeRay is used for source code highlighting.

CodeRay

WARNING

skipping reference to missing attribute: <x>

An attribute cannot be resolved and the attribute-missing attribute is set to skip.

[catch-a-missing-or-undefined-attribute]

WARNING

tables must have at least one body row

Tables

WARNING

tag '<x>' not found in include file: <file>

You tried to include by tagged region, but the included document does not have that tag.

Select Portions of a Document to Include

WARNING

<docname>: id assigned to <type> already in use: <id>

<id> is a duplicate ID, meaning it has already been assigned to a node of <type> (e.g., section, block, anchor). If you don’t see the problem in <docname>, check that the duplicate ID isn’t coming from a file which is being included.

WARNING

<docname> callout list item index: expected <x> got <y>

Callouts are expected to be in numerical order, just like any ordered list.

Callouts

WARNING

<docname> include <x> not readable: <y>

If <y> is a file, do you have read permissions for it? If it is a URI and -a allow-uri-read is set, does it exist?

WARNING

<docname> include file not found: <file>

Probably a typo or missing file. If not, make sure you understand the search process.

Include Directive, File resolution

WARNING

<docname> invalid empty <x> detected in style attribute

The first positional attribute in the block attributes could not be parsed.

Options

WARNING

<docname> invalid style for <x> block: <y>

You have added a custom style to a block, but you haven’t registered a custom block extension to handle it.

WARNING

<docname> invalid style for paragraph: <x>

You have a line [xxx] before a paragraph, but xxx isn’t one of the built-in styles.

Style

WARNING

<docname> list item index: expected <x>, got <y>

You gave explicit numbers on an ordered list, but they were not sequential. Asciidoctor renumbers them for you, and gives this warning.

Ordered Lists

WARNING

<docname> multiple ids detected in style attribute

Multiple IDs cannot be specified in the block style (e.g., [#cat#dog]).

Id

WARNING

<docname> no callouts refer to list item <x>

The callout is missing or not recognized. In source listings, is the callout the last thing on the line?

Callouts

WARNING

<docname> section title out of sequence

Invalid document structure. Check section levels.

Sections