VRL Error Reference

VRL is fail-safe, meaning that a VRL program will not compile unless every possible error is handled. This largely contributes to VRL's safety principle. Observability data is notoriously unpredictable and fail-safety ensures that your VRL programs elegantly handle malformed data, a problem that often plagues observability pipelines.

Compile-time Errors

A compile-time error happens during program compilation (at Vector boot), and prevents a VRL program from compiling. These errors must be resolved before a VRL program can be used. VRL strives to catch as many errors as possible at compile-time to ensure runtime reliability.

100 Unhandled root runtime error

A root expression is fallible and its runtime error isn't handled in the VRL program.

  • Rationale

    VRL is fail safe and thus requires that all possible runtime errors be handled. This provides important safety guarantees to VRL and helps to ensure that VRL programs run reliably when deployed.

  • Resolution

    Handle the runtime error by assigning, coalescing, or raising the error.

  • Examples

    get_env_var("HOST")
    error: Unhandled root runtime error
      ┌─ :1:1
      │
    1 │     (5 / 2)
      │     ^^^^^
      │     │
      │     this expression is unhandled
      │

    This error can be resolved with the following change:

    -   get_env_var("HOST")
    +#  .host = get_env_var("HOST")

101 Malformed regex literal

A regex literal expression is malformed and thus doesn't result in a valid regular expression.

  • Rationale

    Invalid regular expressions don't compile.

  • Resolution

    Regular expressions are difficult to write and commonly result in syntax errors. If you're parsing a common log format we recommend using one of VRL's parse_* functions. If you don't see a function for your format please request it. Otherwise, use the Rust regex tester to test and correct your regular expression.

  • Examples

    . |= parse_regex!(.message, r'^(?P<host>[\w\.]+) - (?P<user>[\w]+) (?P<bytes_in>[\d]+) \[?P<timestamp>.*)\] "(?P<method>[\w]+) (?P<path>.*)" (?P<status>[\d]+) (?P<bytes_out>[\d]+)$')
    error: Malformed regex literal
      ┌─ :1:1
      │
    1 │     . |= parse_regex(.message, r'^(?P<host>[\w\.]+) - (?P<user>[\w]+) (?P<bytes_in>[\d]+) \[?P<timestamp>.*)\] "(?P<method>[\w]+) (?P<path>.*)" (?P<status>[\d]+) (?P<bytes_out>[\d]+)$')
      │                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      │                                │
      │                                this regular expression is invalid
      │

    This error can be resolved with the following change:

    -. |= parse_regex!(.message, r'^(?P<host>[\w\.]+) - (?P<user>[\w]+) (?P<bytes_in>[\d]+) \[?P<timestamp>.*)\] "(?P<method>[\w]+) (?P<path>.*)" (?P<status>[\d]+) (?P<bytes_out>[\d]+)$')
    +. |= parse_common_log!(.message)

102 Non-boolean if expression predicate

An if expression predicate doesn't evaluate to a Boolean.

  • Rationale

    VRL doesn't implement "truthy" values (non-Boolean values that resolve to a Boolean, such as 1) since these are common foot-guns that can result in unexpected behavior when used in if expressions. This provides important safety guarantees in VRL and ensures that VRL programs are reliable once deployed.

  • Resolution

    Adjust your if expression predicate to resolve to a Boolean. Helpful functions to solve this include exists and is_nullish.

  • Examples

    Vector event
    {
      "message": "key=value"
    }
    VRL program
    if .message {
        . |= parse_key_value!(.message)
    }
    error: Non-boolean if expression predicate
      ┌─ :1:1
      │
    1 │     if .message {
      │        ^^^^^^^^
      │        │
      │        if expression predicates must resolve to a strict boolean
      │

    This error can be resolved with the following change:

    -if .message {
    +if exists(.message) {
        . |= parse_key_value!(.message)
     }

103 Unhandled assignment runtime error

The right-hand side of an assignment expression is fallible and can produce a runtime error, but the error isn't being handled.

  • Rationale

    VRL is fail safe and thus requires that all possible runtime errors be handled. This provides important safety guarantees to VRL and helps to ensure that VRL programs run reliably when deployed.

  • Resolution

    Handle the runtime error by assigning, coalescing, or raising the error.

  • Examples

    Unhandled assignment runtime error (coalescing)
    Vector event
    {
      "message": "key=value"
    }
    VRL program
    . |= parse_key_value(.message)
    error: Unhandled assignment runtime error
      ┌─ :1:1
      │
    1 │ . |= parse_key_value(.message)
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      │ │
      │ This assingment does not handle errors
      │

    This error can be resolved with the following change:

    -. |= parse_key_value(.message)
    +. |= parse_key_value(.message) ?? {}

104 Unnecessary error assignment

The left-hand side of an assignment expression needlessly handles errors even though the right-hand side can't fail.

  • Rationale

    Assigning errors when one is not possible is effectively dead code that makes your program difficult to follow. Removing the error assignment simplifies your program.

  • Resolution

    Remove the error assignment.

  • Examples

    .message, err = downcase(.message)
    error: Unnecessary error assignment
      ┌─ :1:1
      │
    1 │ .message, err = downcase(.message)
      │           ^^^
      │           │
      │           unneeded error assignment
      │

    This error can be resolved with the following change:

    -.message, err = downcase(.message)
    +.message = downcase(.message)

105 Undefined function

A function call expression invokes an unknown function.

  • Resolution

    This is typically due to a typo. Correcting the function name should resolve this.

  • Examples

    parse_keyvalue(.message)
    error: Undefined function
      ┌─ :1:1
      │
    1 │ parse_keyvalue(.message)
      │ ^^^^^^^^^^^^^^
      │ │
      │ Undefined function
      │

    This error can be resolved with the following change:

    -parse_keyvalue(.message)
    +parse_key_value(.message)

106 Function argument arity mismatch

A function call expression invokes a function with too many arguments.

  • Resolution

    Remove the extra arguments to adhere to the function's documented signature.

  • Examples

    parse_json(.message, pretty: true)
    error: Function argument arity mismatch
      ┌─ :1:1
      │
    1 │ parse_json(.message, pretty: true)
      │                      ^^^^^^^^^^^^
      │                      │
      │                      This argument exceeds the function arity
      │

    This error can be resolved with the following change:

    -parse_json(.message, pretty: true)
    +parse_json(.message)

107 Required function argument missing

A function call expression fails to pass a required argument.

  • Resolution

    Supply all of the required function arguments to adhere to the function's documented signature.

  • Examples

    parse_timestamp(.timestamp)
    error: Required function argument missing
      ┌─ :1:1
      │
    1 │ parse_timestamp(.timestamp)
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^
      │ │
      │ The required `format` argument is missing
      │

    This error can be resolved with the following change:

    -parse_timestamp(.timestamp)
    +parse_timestamp(.timestamp, format: "%D")

108 Unknown function argument keyword

A function call expression passes an unknown named argument.

  • Resolution

    Correct the name to align with the documented argument names for the function.

  • Examples

    parse_timestamp(.timestamp, fmt: "%D")
    error: Unknown function argument keyword
      ┌─ :1:1
      │
    1 │ parse_timestamp(.timestamp, fmt: "%D")
      │                             ^^^
      │                             │
      │                             The `fmt` argument is unknown
      │

    This error can be resolved with the following change:

    -parse_timestamp(.timestamp)
    +parse_timestamp(.timestamp, format: "%D")

109 Cannot abort function

A function call expression can't end with ! unless it's fallible. If a function can't produce a runtime error, it doesn't have an abort variant that ends with !.

  • Resolution

    Remove the ! from the end of the function name.

  • Examples

    downcase!(.message)
    error: Cannot abort function
      ┌─ :1:1
      │
    1 │ downcase!(.message)
      │         ^
      │         │
      │         This function is not fallible
      │

    This error can be resolved with the following change:

    -downcase!(.message)
    +downcase(.message)

110 Invalid argument type

An argument passed to a function call expression isn't a supported type.

  • Rationale

    VRL is type safe and requires that types align upon compilation. This provides important safety guarantees to VRL and helps to ensure that VRL programs run reliably when deployed.

  • Resolution

    You must guarantee the type of the variable by using the appropriate type#type) or coercion#coerce) function.

  • Examples

    Invalid argument type (guard with defaults)
    downcase(.message)
    error: Invalid argument type
      ┌─ :1:1
      │
    1 │ downcase(.message)
      │          ^^^^^^^^
      │          │
      │          this expression resolves to unknown type
      |          but the parameter "value" expects the exact type "string"
      │

    This error can be resolved with the following change:

    +.message = string(.message) ?? ""
     downcase(.message)

Runtime Errors

A runtime error happens after compilation and during program runtime. Because VRL is fail-safe, runtime errors must be handled, forcing you to address how VRL programs should respond to errors.

Runtime errors are nothing more than simple strings that describe the error.

Handling

When it comes to runtime error handling in VRL you have three options: assign the error, coalescing the error, or raise the error. With these three options you can elegantly handle errors to ensure your VRL scripts are resilient to problems.

Assigning

As documented in the assignment expression reference, you can assign errors when invoking an expression that is fallible. When assigned, runtime errors are simple strings:

structured, err = parse_json("not json")
if err != null {
  log("Unable to parse JSON: " + err, level: "error")
} else {
  . = merge(., structured)
}

Coalescing

As documented in the coalesce expression reference, you can coalesce errors to efficiently step through multiple expressions:

structured = parse_json("not json") ?? parse_syslog("not syslog") ?? {}
. = merge(., structured)

Raising

As documented in the function call expression reference, you can raise errors to immediately abort the program by adding a ! to the end of the function name:

structured = parse_json!("not json")
. = merge(., structured)
Contents
Resources