Skip to main content

OPA Errors Guide

This guide is designed to help you understand the most common errors you'll encounter when working with OPA. Each document provides examples of the error, why it's an error, and how to fix it. A perfect companion for your debugging session!

The errors currently documenteded are:

parsingrego_parse_errorvar cannot be used for rule name
parsingrego_parse_errorunexpected {name} keyword
parsingrego_parse_errorunexpected assign token
parsingrego_parse_errorunexpected { token
parsingrego_parse_errorunexpected identifier token
parsingrego_parse_errorunexpected } token
parsingrego_parse_errorunexpected string token
compilationrego_recursion_errorrule {name} is recursive
compilationrego_type_errorconflicting rules {name} found
compilationrego_type_errormatch error
compilationrego_type_errorarity mismatch
compilationrego_type_errorfunction has arity
compilationrego_type_errorunsafe built-in function calls in expression: {name}
compilationrego_unsafe_var_errorvar {name} is unsafe
compilationrego_compile_errorassigned var {name} unused
evaluationeval_conflict_errorcomplete rules must not produce multiple outputs
evaluationeval_conflict_errorobject keys must be unique

How To Read This Guide

Each document provides the following information:



The category of the error. This is a high-level grouping of errors that are related to each other.


The error message you'll see OPA emit (normally following the category).


Evaluation of Rego policies happens in three distinct stages — parsing, compilation and evaluation. Errors reported in any of these stages will stop the evaluation process and have the error(s) reported.


The first stage is parsing. In this step, OPA takes the raw Rego policy and parses it into an abstract syntax tree (AST), which is then handed to the compiler. Errors at this stage are normally syntax errors, meaning the Rego provided in a policy simply isn't valid. An example of this might be forgetting to terminate a string with a closing quote:

package policy

import future.keywords.contains
import future.keywords.if

deny contains message if {
# ...

message := "This won't work!

As expected, OPA will report a syntax error:

2 errors occurred:
policy.rego:9: rego_parse_error: non-terminated string
message := "This won't work!
policy.rego:9: rego_parse_error: illegal token
message := "This won't work!

At this point, further processing isn't possible, and the error must be fixed before we can proceed.


While we may not think of Rego as a "compiled language", any policy passes through a compilation step before it can be evaluated. During compilation, OPA will run several stages of analysis on the policy (which is now an AST) to ensure that it's valid. This includes things like checking that functions are called with the right number of arguments, that types are used correctly, or that variables are defined before they're used. A typical example of a compilation error would be referencing a rule that isn't defined:

package policy

x := y

Since y isn't defined in our policy, the compiler considers it unsafe:

1 error occurred: policy.rego:3: rego_unsafe_var_error: var y is unsafe

Tip: when using opa eval, you can pass the --strict flag to enable additional compiler checks — like unused variables or function arguments. This is a great way to spot mistakes and errors as soon as possible, and is highly recommended.


The last stage in which errors may appear is evaluation. Errors at this stage normally involve input or data that isn't known to OPA during parsing or compilation. Consider the following simplified example:

package policy

x := input.x

x := input.y

This policy might work, if only one of x or y is provided in the input. If both are provided, and they have different, conflicting, values — an error will be reported during the evaluation stage:

policy.rego:3: eval_conflict_error: complete rules must not produce multiple outputs

Important to know is that not all "errors" at this stage will be reported as errors! Some things that would be considered an error during compilation, like passing the wrong type of value in a function argument, would simply result in evaluation being undefined during evaluation time.

startswith("100", 1)

As the startswith function expects two strings — and this is known by the compiler — this would fail during compilation. But if we replace the 1 with a value from input:

startswith("100", input.x)

The compiler can't know the value of input.x. During evaluation, we do know the value of input.x, but does it mean we want a malformed value to stop policy evaluation entirely? Probably not! By default, evaluation will simply consider that case to be undefined, and move on with evaluating the rest of the policy.

Tip: If you're using opa eval to evaluate policies, you can pass the --strict-builtin-errors flag to have an error from a built-in function halt evaluation and have the error reported. Additionally, the --show-builtin-errors flag may be used to collect all errors from calling built-in functions and have them reported. Both of these flags can be very useful for debugging!

How To Fix It

This section provides guidance on how to fix the error.

More Information

Some pages may provide additional information about the error, as well as links to resources for further reading.