Log Failure Level

The failure_level key specifies the severity threshold that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code.

Default failure level

Explicitly assigning a value to the failure_level key is optional. If it isn’t set in the playbook or specified using the --log-failure-level option or ANTORA_LOG_FAILURE_LEVEL variable, Antora assigns the value fatal to the key at runtime. If a logged message meets the fatal severity threshold, Antora will exit with a non-zero exit code.

failure_level key

The failure_level key is configured under the runtime and log keys in a playbook.

Example 1. antora-playbook.yml
runtime:
  log:
    failure_level: error

The key accepts the following built-in values:

  • fatal (default)

  • error

  • warn

  • none

These values correspond to the severity levels Antora assigns to log messages. Except when the value is none, Antora exits with a non-zero exit code if a message is logged that meets or exceeds the value assigned to failure_level. Note that when Antora’s logger is turned off, the failure_level key and its value aren’t applied.

Force zero exit code

The behavior of none, described in this section, hasn’t been implemented yet. See issue #788 for updates.

When the failure_level key is assigned the value none, Antora always exits with the exit code zero (0), even if a fatal error is encountered.

Specify a failure level

Let’s assign the value warn to the failure_level key in the playbook shown in Example 2.

Example 2. Assign warn severity threshold to failure_level key
runtime:
  log:
    failure_level: warn

Antora will finish generating the site, as long as it doesn’t encounter any fatal errors, and exit with a non-zero exit code if any messages are logged with a severity of warn or greater. If no warning, error, or fatal messages are logged, Antora exits with a zero (0) exit code. That is, your site built successfully without any errors or potential problems!

Log failure level option

Alternatively, you can use the --log-failure-level option from the CLI to assign a failure threshold.

$ antora --failure-level=warn antora-playbook.yml

The --log-failure-level option overrides the value assigned to the failure_level key or the ANTORA_LOG_FAILURE_LEVEL environment variable.