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
andis_nullish
.Examples
Vector event{"message": "key=value"}VRL programif .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)