https://www.openpolicyagent.org/assets/js/ed6c4993.7ffb1aef.js

1"use strict";(self.webpackChunkopa_website=self.webpackChunkopa_website||[]).push([[15480],{28453:(e,r,n)=>{n.d(r,{R:()=>t,x:()=>l});var i=n(96540);const s={},o=i.createContext(s);function t(e){const r=i.useContext(o);return i.useMemo((function(){return"function"==typeof e?e(r):{...r,...e}}),[r,e])}function l(e){let r;return r=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:t(e.components),i.createElement(o.Provider,{value:r},e.children)}},38912:(e,r,n)=>{n.r(r),n.d(r,{assets:()=>d,contentTitle:()=>l,default:()=>h,frontMatter:()=>t,metadata:()=>i,toc:()=>a});const i=JSON.parse('{"id":"errors/index","title":"OPA Errors Guide","description":"This guide is designed to help you understand the most common errors you\'ll encounter when working with OPA. Each","source":"@site/docs/errors/index.md","sourceDirName":"errors","slug":"/errors/","permalink":"/docs/errors/","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_label":"Overview","sidebar_position":1,"image":"/img/opa-errors.png"},"sidebar":"docsSidebar","previous":{"title":"Style Guide","permalink":"/docs/style-guide"},"next":{"title":"complete rules must not produce multiple outputs","permalink":"/docs/errors/eval-conflict-error/complete-rules-must-not-produce-multiple-outputs"}}');var s=n(74848),o=n(28453);const t={sidebar_label:"Overview",sidebar_position:1,image:"/img/opa-errors.png"},l="OPA Errors Guide",d={},a=[{value:"How To Read Pages in this Section",id:"how-to-read-pages-in-this-section",level:2},{value:"Metadata",id:"metadata",level:3},{value:"Stage",id:"stage",level:3},{value:"Parsing",id:"parsing",level:4},{value:"Compilation",id:"compilation",level:4},{value:"Evaluation",id:"evaluation",level:4},{value:"How To Fix It",id:"how-to-fix-it",level:3},{value:"More Information",id:"more-information",level:3}];function c(e){const r={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(r.header,{children:(0,s.jsx)(r.h1,{id:"opa-errors-guide",children:"OPA Errors Guide"})}),"\n",(0,s.jsx)(r.p,{children:"This guide is designed to help you understand the most common errors you'll encounter when working with OPA. Each\ndocument provides examples of the error, why it's an error, and how to fix it."}),"\n",(0,s.jsx)(r.p,{children:"The errors currently documented are:"}),"\n",(0,s.jsxs)(r.table,{children:[(0,s.jsx)(r.thead,{children:(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.th,{children:"Stage"}),(0,s.jsx)(r.th,{children:"Category"}),(0,s.jsx)(r.th,{children:"Message"})]})}),(0,s.jsxs)(r.tbody,{children:[(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-parse-error/var-cannot-be-used-for-rule-name",children:"var cannot be used for rule name"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-parse-error/unexpected-name-keyword",children:["unexpected ",(0,s.jsx)(r.code,{children:"{name}"})," keyword"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-parse-error/unexpected-assign-token",children:"unexpected assign token"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-parse-error/unexpected-left-curly-token",children:["unexpected ",(0,s.jsx)(r.code,{children:"{"})," token"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-parse-error/unexpected-identifier-token",children:"unex

1pected identifier token"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-parse-error/unexpected-right-curly-token",children:["unexpected ",(0,s.jsx)(r.code,{children:"}"})," token"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"parsing"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_parse_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-parse-error/unexpected-string-token",children:"unexpected string token"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_recursion_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-recursion-error/rule-name-is-recursive",children:["rule ",(0,s.jsx)(r.code,{children:"{name}"})," is recursive"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_type_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-type-error/conflicting-rules-name-found",children:["conflicting rules ",(0,s.jsx)(r.code,{children:"{name}"})," found"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_type_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-type-error/match-error",children:"match error"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_type_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-type-error/arity-mismatch",children:"arity mismatch"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_type_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/rego-type-error/function-has-arity-got-argument",children:"function has arity"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_type_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-type-error/unsafe-built-in-function-calls-in-expression-name",children:["unsafe built-in function calls in expression: ",(0,s.jsx)(r.code,{children:"{name}"})]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_unsafe_var_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-unsafe-var-error/var-name-is-unsafe",children:["var ",(0,s.jsx)(r.code,{children:"{name}"})," is unsafe"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"compilation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"rego_compile_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsxs)(r.a,{href:"./errors/rego-compile-error/assigned-var-name-unused",children:["assigned var ",(0,s.jsx)(r.code,{children:"{name}"})," unused"]})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"evaluation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"eval_conflict_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/eval-conflict-error/complete-rules-must-not-produce-multiple-outputs",children:"complete rules must not produce multiple outputs"})})]}),(0,s.jsxs)(r.tr,{children:[(0,s.jsx)(r.td,{children:"evaluation"}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.code,{children:"eval_conflict_error"})}),(0,s.jsx)(r.td,{children:(0,s.jsx)(r.a,{href:"./errors/eval-conflict-error/object-keys-must-be-unique",children:"object keys must be unique"})})]})]})]}),"\n",(0,s.jsx)(r.h2,{id:"how-to-read-pages-in-this-section",children:"How To Read Pages in this Section"}),"\n",(0,s.jsx)(r.p,{children:"Each page in the OPA errors guide goes into detail about a single OPA error\ntype. For each detailed page, it contains the following information to help you\nboth check it applies and to resolve the error."}),"\n",(0,s.jsx)(r.h3,{id:"metadata",children:"Metadata"}),"\n",(0,s.jsxs)(r.ul,{children:["\n",(0,s.jsxs)(r.li,{children:[(0,s.jsx)(r.strong,{children:"Category"}),": The category of the error. This is a high-level grouping of errors that are related to each other."]}

1),"\n",(0,s.jsxs)(r.li,{children:[(0,s.jsx)(r.strong,{children:"Message"}),": The error message you'll see OPA emit (normally following the category)."]}),"\n"]}),"\n",(0,s.jsx)(r.h3,{id:"stage",children:"Stage"}),"\n",(0,s.jsx)(r.p,{children:"Evaluation of Rego policies happens in three distinct stages \u2014 parsing, compilation and evaluation. Errors reported in\nany of these stages will stop the evaluation process and have the error(s) reported."}),"\n",(0,s.jsx)(r.h4,{id:"parsing",children:"Parsing"}),"\n",(0,s.jsxs)(r.p,{children:["The first stage is ",(0,s.jsx)(r.strong,{children:"parsing"}),". In this step, OPA takes the raw Rego policy and parses it into an abstract syntax tree\n(AST), which is then handed to the compiler. Errors at this stage are normally syntax errors, meaning the Rego provided\nin a policy isn't valid. An example of this might be forgetting to terminate a string with a closing quote:"]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-rego",children:"package policy\n\nimport future.keywords.contains\nimport future.keywords.if\n\ndeny contains message if {\n    # ...\n\n    message := \"This won't work!\n}\n"})}),"\n",(0,s.jsx)(r.p,{children:"As expected, OPA will report a syntax error:"}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-txt",children:"2 errors occurred:\npolicy.rego:9: rego_parse_error: non-terminated string\n        message := \"This won't work!\n                   ^\npolicy.rego:9: rego_parse_error: illegal token\n        message := \"This won't work!\n                   ^\n"})}),"\n",(0,s.jsx)(r.p,{children:"At this point, further processing isn't possible, and the error must be fixed before proceeding."}),"\n",(0,s.jsx)(r.h4,{id:"compilation",children:"Compilation"}),"\n",(0,s.jsx)(r.p,{children:"While Rego may not seem like a \"compiled language\", any policy passes through a compilation step before it can be\nevaluated. During compilation, OPA will run several stages of analysis on the policy (which is now an AST) to ensure\nthat it's valid. This includes things like checking that functions are called with the right number of arguments,\nthat types are used correctly, or that variables are defined before they're used. A typical example of a compilation\nerror would be referencing a rule that isn't defined:"}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-rego",children:"package policy\n\nx := y\n"})}),"\n",(0,s.jsxs)(r.p,{children:["Since ",(0,s.jsx)(r.code,{children:"y"})," isn't defined in the policy, the compiler considers it unsafe:"]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-txt",children:"1 error occurred: policy.rego:3: rego_unsafe_var_error: var y is unsafe\n"})}),"\n",(0,s.jsxs)(r.p,{children:[(0,s.jsx)(r.strong,{children:"Tip:"})," when using ",(0,s.jsx)(r.code,{children:"opa eval"}),", you can pass the ",(0,s.jsx)(r.code,{children:"--strict"})," flag to enable additional compiler checks \u2014 like unused\nvariables or function arguments. This helps catch mistakes and errors early, and is highly\nrecommended."]}),"\n",(0,s.jsx)(r.h4,{id:"evaluation",children:"Evaluation"}),"\n",(0,s.jsxs)(r.p,{children:["The last stage in which errors may appear is evaluation. Errors at this stage normally involve ",(0,s.jsx)(r.code,{children:"input"})," or ",(0,s.jsx)(r.code,{children:"data"}),"\nthat isn't known to OPA during parsing or compilation. Consider the following simplified example:"]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-rego",children:"package policy\n\nx := input.x\n\nx := input.y\n"})}),"\n",(0,s.jsxs)(r.p,{children:["This policy ",(0,s.jsx)(r.em,{children:"might"})," work, if only one of ",(0,s.jsx)(r.code,{children:"x"})," or ",(0,s.jsx)(r.code,{children:"y"})," is provided in the input. If ",(0,s.jsx)(r.em,{children:"both"})," are provided, and they have\ndifferent, conflicting, values \u2014 an error will be reported during the evaluation stage:"]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-sh",children:"policy.rego:3: eval_conflict_error: complete rules must not produce multiple outputs\n"})}),"\n",(0,s.jsx)(r.p,{children:'Important to know is that not all "errors" at this stage will be reported as errors! Some things that would be\nconsidered an error during compilation, like passing the wrong type of value in a function argument, would instead leave the result undefined at evaluation time.'}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-rego",children:'startswith("100", 1)\n'})}),"\n",(0,s.jsxs)(r.p,{children:["As the ",(0,s.jsx)(r.code,{children:"startswith"})," function expects two strings \u2014 and this is known by the compiler \u2014 this would fail during\ncompilation. If the ",(0,s.jsx)(r.code,{children:"1"})," is replaced with a value from ",(0,s.jsx)(r.code,{children:"input"}),":"]}),"\n",(0,s.jsx)(r.pre,{children:(0,s.jsx)(r.code,{className:"language-rego",children:'startswith("100", input.x)\n'})}),"\n",(0,s.jsxs)(r.p,{children:["The compiler can't know the value of ",(0,s.jsx)(r.code,{children:"input.x"}),". At evaluation time, the value is known, but a\nmalformed value does not stop policy evaluation entirely. By default, evaluation\nwill consider that case to be ",(0,s.jsx)(r.em,{children:"undefined"}),", and move on with evaluating the rest of the policy."]}),"\n",(0,s.jsxs)(r.p,{children:[(0,s.jsx)(r.strong,{children:"Tip:"})," If you're using ",(0,s.jsx)(r.code,{children:"opa eval"})," to evaluate policies, you can pass the ",(0,s.jsx)(r.code,{children:"--strict-builtin-errors"})," flag to have\nan error from a built-in function halt evaluation and have the error reported. Additionally, the\n",(0,s.jsx)(r.code,{children:"--show-builtin-errors"})," flag may be used to collect ",(0,s.jsx)(r.em,{children:"all"})," errors from calling built-in functions and have them\nreported. Both of these flags can be very useful for debugging!"]}),"\n",(0,s.jsx)(r.h3,{id:"how-to-fix-it",children:"How To Fix It"}),"\n",(0,s.jsx)(r.p,{children:"This section provides guidance on how to fix the error."}),"\n",(0,s.jsx)(r.h3,{id:"more-information",children:"More Information"}),"\n",(0,s.jsx)(r.p,{children:"Some pages may provide additional information about the error, as well as links to resources for further reading."})]})}function h(e={}){const{wrapper:r}={...(0,o.R)(),...e.components};return r?(0,s.jsx)(r,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}}}]);