# Errors and Warnings

All application messages (i.e., debug, info, warning, error, or fatal) emitted by Asciidoctor are written to the logger. By default, only warning, error, and fatal messages are logged. When using the CLI, the logger routes messages to the console via stderr (i.e., standard error).

## Notification types

DEBUG

Debug messages provide insight into what the software is doing and can be useful for tracking down problems or unexpected behavior. Currently, Asciidoctor does not log any messages at this level. However, extensions may do so.

INFO

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

WARN (WARNING)

Warnings do not stop conversion, but they indicate likely problems, and the output probably won’t be what you were expecting. In the CLI output, Asciidoctor labels these messages as WARNING rather than WARN.

ERROR

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

FATAL (FAILED)

Failures are fatal; no output document will be produced. If the --trace CLI option is specified, the message may be accompanied by a stacktrace. In the CLI output, Asciidoctor labels these messages as FAILED rather than FATAL.

The messages listed in the following sections may contain some of the following representative 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 (i.e., URL) being referenced.

<x> or <y>

Placeholders for other contextual information in the message.

## Info messages

Message Troubleshooting

possible invalid reference: <x>

The processor could not validate the internal reference named <x>. This message doesn’t definitively indicate a missing reference. Rather, it indicates the reference (i.e., anchor) is not in a location where the reference can be validated.

## Warning messages

Message Troubleshooting

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

Invalid book document structure.

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

Reading from a URI is only allowed if the allow-uri-read attribute is set from the CLI or API.

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

Web address not found.

could not retrieve image data from URI: <uri>

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

dropping line containing reference to missing attribute: <x>

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

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.

gem 'concurrent-ruby' is not installed. This gem is recommended when registering custom converters.

You have registered a custom converter, and you have not installed the concurrent-ruby gem.

gem 'concurrent-ruby' 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 concurrent-ruby gem.

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

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

include file not readable: <file>

You do not have permission to access the file.

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

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

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

asciimath is a required library when converting AsciiMath expressions in AsciiDoc to DocBook.

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

Rouge is used for source code highlighting when source-highlighter is set to rouge.

skipping reference to missing attribute: <x>

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

tables must have at least one body row

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

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

<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.

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

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

<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?

<docname> include file not found: <file>

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

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

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

<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.

<docname> invalid style for paragraph: <x>

You have a line [<name-of-style>] before a paragraph, but name-of-style isn’t a recognized built-in style.

<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.

<docname> multiple ids detected in style attribute

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

<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?

<docname> section title out of sequence

Invalid document structure. Check section levels.

## Error messages

Message Troubleshooting

input file <file> missing or cannot be read

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

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.

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

Choose a different output directory or filename.

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.

unmatched macro: endif::<x>[]

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

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

<docname> illegal block content outside of partintro block

Invalid book document structure.

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

Invalid book document structure.

<docname> malformed manpage title

Document does not conform to the structure required by the declared manpage doctype.

<docname> malformed name section body

Document does not conform to the structure required by the declared manpage doctype.

<docname> maximum include depth of 64 exceeded

Does your file include itself, directly or indirectly?

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

ifdef/endif blocks must be strictly nested.

<docname> name section expected

Document does not conform to the structure required by the declared manpage doctype.

<docname> name section title must be at level 1

Document does not conform to the structure required by the declared manpage doctype.

<docname> only book doctypes can contain level 0 sections

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

<docname> table missing leading separator, recovering automatically

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

## Fatal messages

Message Troubleshooting

missing converter for backend '<x>'. Processing aborted.

You used -b with an invalid or missing backend.

'tilt' could not be loaded

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