VRL error reference

VRL is a fail-safe language, which means that a VRL program doesn't compile unless every potential error is handled. Observability data is notoriously unpredictable and fail safety ensures that your VRL programs elegantly handle malformed data.

linkCompile-time errors

{{< vrl/errors/compile-time >}}

linkRuntime errors

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

Runtime errors are strings that describe the error.

linkHandling

You have three options for handling errors in VRL:

• Assign the error
• Coalesce the error
• Raise the error

linkAssigning

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

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

If the expression fails, the ok assignment target is assigned the "empty" value of its type:

1# `.foo` can be `100` or `"not an int"`
2foo, err = to_int(.foo)
3
4# `err` can be `null` or `"unable to coerce value to integer"`
5if err == null {
6  # `foo` can be `100` or `0`
7  .result = foo * 5
8}

The above example compiles because foo will either be assigned the integer representation of .foo if it can be coerced to an integer, or it will be set to the "empty integer value" 0 if .foo can't be coerced into an integer.

Because of this, it is important to always check if err is null before using the ok value of an infallible assignment.

linkEmpty values

Type	Empty value
String	""
Integer	0
Float	0.0
Boolean	false
Object	{}
Array	[]
Timestamp	t'1970-01-01T00:00:00Z' (Unix epoch)
Regular expression	r''
Null	null

linkCoalescing

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

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

linkRaising

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

1structured = parse_json!("not json")
2. = merge(., structured)

{{< warning title="Raising errors should be used with caution" >}} While raising errors can simplfy your program, you should think carefully before aborting your program. If this operation is critical to the structure of your data you should abort, otherwise consider handling the error and proceeding with the rest of your program. {{< /warning >}}