Skip to content

errors

unit

Usage

A configuration file can have one errors block, holding any number of retry and ignore blocks. This one retries two common network errors:

terragrunt.hcl
errors {
retry "network" {
retryable_errors = [
"connection reset by peer",
"TLS handshake timeout",
]
max_attempts = 3
sleep_interval_sec = 5
}
}

When a command fails with either error, Terragrunt logs a warning, waits 5 seconds, and runs the command again, up to 3 runs in total:

WARN Encountered retryable error: network
Attempt 1 of 3. Waiting 5 second(s) before retrying...

Matching errors

Terragrunt checks an error against the ignore blocks first, then the retry blocks, and the first block that matches handles the error. An error that matches both an ignore and a retry block is ignored, not retried.

A block matches when the error matches at least one of its patterns and none of its ! patterns, wherever the ! pattern sits in the list. Patterns match anywhere in the error, so they need no leading or trailing .*.

For a failed OpenTofu/Terraform command, the error is the command’s stderr. Before matching, Terragrunt replaces every character other than letters, digits, spaces, and . / ' " ( ) : = - with a space, and joins the lines with single spaces. Write patterns against that text. An error that mentions missing_file.txt matches missing file but not missing_file:

terragrunt.hcl
errors {
ignore "missing_file" {
ignorable_errors = ["no file exists at .*missing file"]
}
}

Error signals

The signals of an ignore block tell automation what to do about an ignored error. Terragrunt writes them to error-signals.json in the unit’s directory:

{
"safe_to_revert": true
}

A CI/CD pipeline can act on them, e.g. find every unit whose error-signals.json sets safe_to_revert, check out the previous commit for those units, and apply them to revert the change.

Examples

Retries a transient network error up to twice, and ignores a known safe warning unless the error also matches the negative pattern.

terragrunt.hcl
errors {
retry "transient_errors" {
retryable_errors = ["Error: transient network issue"]
max_attempts = 3
sleep_interval_sec = 5
}
ignore "known_safe_errors" {
ignorable_errors = [
"Error: safe warning",
"!Error: do not ignore",
]
message = "Ignoring safe warning errors"
signals = {
alert_team = false
}
}
}

Retries a source download that fails with a transient error. The errors block handles errors while Terragrunt downloads the module, as well as errors from OpenTofu/Terraform.

terragrunt.hcl
terraform {
source = "https://unreliable-source.com/module.zip"
}
errors {
retry "source_fetch" {
retryable_errors = ["Error: transient network issue"]
max_attempts = 3
sleep_interval_sec = 5
}
}

Blocks

retryretry "<name>" { … }

Runs the command again when its error matches one of retryable_errors. --no-auto-retry turns off retries for a run.

namelabel

Names the rule. Terragrunt logs it with each retry.

retryable_errorslist(string)

Regular expressions for the errors to retry. A pattern that starts with ! keeps a matching error from being retried. See Matching errors.

max_attemptsnumber

How many times to run the command in total, the first run included, e.g. 3 for up to two retries. It must be at least 1.

sleep_interval_secnumber

Seconds to wait between attempts.

terragrunt.hcl
errors {
retry "transient_errors" {
retryable_errors = ["Error: transient"]
max_attempts = 5
sleep_interval_sec = 10
}
}
ignoreignore "<name>" { … }

Treats a matching error as success. Terragrunt logs a warning with message and carries on.

namelabel

Names the rule.

ignorable_errorslist(string)

Regular expressions for the errors to ignore. A pattern that starts with ! keeps a matching error from being ignored. See Matching errors.

messageoptional(string)

The warning Terragrunt logs when it ignores an error.

signalsoptional(map(any))

Values Terragrunt writes as JSON to error-signals.json in the unit’s directory when it ignores an error. See Error signals.

terragrunt.hcl
errors {
ignore "known_safe_errors" {
ignorable_errors = [
"Error: safe-to-ignore",
"!Error: critical",
]
message = "Ignoring safe-to-ignore errors"
signals = {
safe_to_revert = true
}
}
}