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")
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]+)$')
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
existsandis_nullish.Examples
Vector event{"message": "key=value"}VRL programif .message {. |= parse_key_value!(.message)}
103 Unhandled fallible assignment
The right-hand side of this assignment is fallible (that is, it can produce a runtime error), but the error isn't 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 either assigning it, coalescing it, or raising it.
Examples
Unhandled fallible assignment (coalescing)Vector event{"message": "key=value"}VRL program. = 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)
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)
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)
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)
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")
110 Invalid argument type
An argument passed to a function call expression isn't a supported type.
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
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)
203 Unrecognized token
Your VRL program contains a token (character) that the VRL parser doesn't recognize as valid.
Resolution
Use a valid token.
Examples
😂
204 Unrecognized end-of-file (EOF)
The VRL parser has reached the end of the program in an invalid state, potentially due to a typo or a dangling expression.
Resolution
Make sure that the last expression in the program is valid.
Examples
.field1 = "value1".field2 =
205 Reserved keyword
You've used a name for a variable that serves another purpose in VRL or is reserved for potential future use.
Resolution
Use a different variable name.
Examples
else = "some value"
207 Invalid string literal
Your VRL program contains a string literal that the VRL parser doesn't recognize as valid.
Resolution
Make sure that your string is properly enclosed by single or double quotes.
Examples
"Houston, we have a problem'
209 Invalid escape character
Your string includes an escape character that the VRL compiler doesn't recognize as valid
305 Divide by zero
You've attempted to divide an integer or float by zero.
Rationale
Unlike some other programming languages, VRL doesn't have any concept of infinity, as it's unclear how that could be germane to observability data use cases. Thus, dividing by zero can't have any meaningful result.
Resolution
If you know that a value is necessarily zero, don't divide by it. If a value could be zero, capture the potential error thrown by the operation:
result, err = 27 / .some_valueif err != nil {# Handle error}
312 Greater than or equal to error
These two values can't be used in a greater than or equal to expression.
314 Less than or equal to error
These two values can't be used in a less than or equal to expression.
401 Invalid enum variant
VRL expects an enum value for this argument, but the value you entered for the enum is invalid.
Resolution
Check the documentation for this function in the VRL functions reference to see which enum values are valid for this argument.
601 Invalid timestamp
The provided timestamp literal is properly
formed (i.e. it uses t'...' syntax) but the timestamp doesn't adhere to RFC 3339 format.
Rationale
Invalid timestamps don't compile.
Resolution
Bring the timestamp in conformance with RFC 3339 format.
Examples
.timestamp = format_timestamp!(t'next Tuesday', format: "%v %R")
620 Aborting infallible function
You've specified that a function should abort on error even though the function is infallible.
Rationale
In VRL, infallible functions—functions that can't fail—don't require error handling, which in turn means it doesn't make sense to abort on failure using a
!in the function call.Resolution
Remove the
!from the function call.Examples
encode_json!(["one", "two", "three"])
630 Fallible argument
You've passed a fallible expression as an argument to a function.
Rationale
In VRL, expressions that you pass to functions as arguments need to be infallible themselves. Otherwise, the outcome of the function would be indeterminate.
Resolution
Make the expression passed to the function infallible, potentially by aborting on error using
!, coalescing the error using??, or via some other method.Examples
format_timestamp!(to_timestamp("2021-01-17T23:27:31.891948Z"), format: "%v %R")
640 No-op assignment
You've assigned a value to something that is neither a variable nor a path.
Rationale
All assignments in VRL need to be to either a path or a variable. If you try to assign a value to, for example, underscore (
_), this operation is considered a "no-op" as it has no effect (and is thus not an assignment at all).Resolution
Assign the right-hand-side value to either a variable or a path.
Examples
_ = "the hills are alive"
650 Chained comparison operators
You've chained multiple comparison operators together in a way that can't result in a valid expression.
Rationale
Comparison operators can only operate on two operands, e.g.
1 != 2. Chaining them together, as in1 < 2 < 3, produces a meaningless non-expression.Resolution
Use comparison operators only on a left-hand- and a right-hand-side value. You can chain comparisons together provided that the expressions are properly grouped. While
a == b == c, for example, isn't valid,a == b && b == cis valid because it involves distinct Boolean expressions.Examples
1 == 1 == 2
651 Unnecessary error coalescing operation
You've used a coalescing operation (??) to handle an error, but in this case the left-hand
operation is infallible, and so the right-hand value after ?? is never reached.
Rationale
Error coalescing operations are useful when you want to specify what happens if an operation fails. Here's an example:
result = op1 ?? op2In this example, if
op1is infallible (that is, it can't error) then theresultvariable if set to the value ofop1whileop2is never reached.Resolution
If the left-hand operation is meant to be infallible, remove the
??operator and the right-hand operation. If, however, the left-hand operation is supposed to be fallible, remove the!from the function call and anything else that's making it infallible.
652 Only objects can be merged
You're attempting to merge two values together but one or both isn't an object.
Rationale
Amongst VRL's available types, only objects can be merged together. It's not clear what it would mean to merge, for example, an object with a Boolean. Please note, however, that some other VRL types do have merge-like operations available:
- Strings can be concatenated together
- Arrays can be appended to other arrays
These operations may come in handy if you've used
mergeby accident.Resolution
Make sure that both values that you're merging are VRL objects. If you're not sure whether a value is an object, you can use the
objectfunction to check.
660 Non-Boolean negation
You've used the negation operator to negate a non-Boolean expression.
Rationale
Only Boolean values can be used with the negation operator (
!). The expression!false, for example, producestrue, whereas!"hello"is a meaningless non-expression.Resolution
Use the negation operator only with Boolean expressions.
Examples
!47
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)}
If the expression fails, the ok assignment target is assigned the "empty" value of its type:
# `.foo` can be `100` or `"not an int"`foo, err = to_int(.foo)# `err` can be `null` or `"unable to coerce value to integer"`if err == null {# `foo` can be `100` or `0`.result = foo * 5}
The above example compiles, because foo will either be assigned the integer representation of .foo if it can be
coerced into 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.
Empty Values
- string:
"" - int:
0 - float:
0.0 - bool:
false - object:
{} - array:
[] - timestamp:
t'1970-01-01T00:00:00Z'(Unix epoch) - regex:
r'' - null:
null
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)