{"record":{"id":"49c15290e6e4b49f","repo":"mikefarah/yq","slug":"value-for-env-variable-v-not-provided-in-env","errorCode":null,"errorMessage":"value for env variable '%v' not provided in env()","messagePattern":"value for env variable '(.+?)' not provided in env\\(\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_env.go","lineNumber":38,"sourceCode":"\tif ConfiguredSecurityPreferences.DisableEnvOps {\n\t\treturn Context{}, fmt.Errorf(\"env operations have been disabled\")\n\t}\n\tenvName := expressionNode.Operation.CandidateNode.Value\n\tlog.Debugf(\"EnvOperator, env name: %v\", envName)\n\n\trawValue := os.Getenv(envName)\n\n\tpreferences := expressionNode.Operation.Preferences.(envOpPreferences)\n\n\tvar node *CandidateNode\n\tif preferences.StringValue {\n\t\tnode = &CandidateNode{\n\t\t\tKind:  ScalarNode,\n\t\t\tTag:   \"!!str\",\n\t\t\tValue: rawValue,\n\t\t}\n\t} else if rawValue == \"\" {\n\t\treturn Context{}, fmt.Errorf(\"value for env variable '%v' not provided in env()\", envName)\n\t} else {\n\t\tdecoder := NewYamlDecoder(ConfiguredYamlPreferences)\n\t\tif err := decoder.Init(strings.NewReader(rawValue)); err != nil {\n\t\t\treturn Context{}, err\n\t\t}\n\t\tvar err error\n\t\tnode, err = decoder.Decode()\n\n\t\tif err != nil {\n\t\t\treturn Context{}, err\n\t\t}\n\n\t}\n\tlog.Debugf(\"ENV tag: %v\", node.Tag)\n\tlog.Debugf(\"ENV value: %v\", node.Value)\n\tlog.Debugf(\"ENV Kind: %v\", node.Kind)\n\n\treturn context.SingleChildContext(node), nil","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_env.go#L20-L56","documentation":"The `env(NAME)` operator returns the value of an environment variable. If the variable is unset (os.Getenv returns \"\"), yq cannot distinguish 'empty on purpose' and treats it as missing, refusing to produce a node. This protects users from silently inserting empty values into their documents.","triggerScenarios":"Evaluating `env(SOME_VAR)` where SOME_VAR is not set in the process environment, or is set to the empty string.","commonSituations":"CI variables not exported to the yq step; typo in variable name; variable defined in .env file not loaded into the actual environment; variable genuinely empty and the user expected an empty string.","solutions":["Export the variable before running yq: export MY_VAR=value","Fix typos in the variable name inside the expression","Provide a fallback in shell: MY_VAR=\"${MY_VAR:-default}\" yq '.x = env(MY_VAR)'","If an empty value is legitimate, use envsubst on a pre-built string or handle emptiness in the shell"],"exampleFix":"// before (MY_VAR unset)\nyq '.url = env(MY_VAR)' file.yaml\n// error: value for env variable 'MY_VAR' not provided in env()\n\n// after\nMY_VAR=https://api.example.com yq '.url = env(MY_VAR)' file.yaml","handlingStrategy":"validation","validationCode":": \"${MY_VAR:?MY_VAR must be set and non-empty}\" && yq '.x = env(MY_VAR)' file.yaml","typeGuard":"def env_or(name, default=None):\n    v = os.environ.get(name)\n    if not v:\n        return default\n    return v","tryCatchPattern":"out=$(yq '.x = env(MY_VAR)' f.yaml 2>&1) || {\n  echo \"env var missing: $out\" >&2\n  exit 2\n}","preventionTips":["Use shell ${VAR:?} to fail fast before invoking yq","Export variables in CI before the yq step","Double-check spelling of variable names in expressions","Provide defaults with ${VAR:-default}"],"tags":["yq","environment","missing-variable"],"backgroundTag":"missing-env-var","analyzedSha":"8b5af0694bb82b41d4ae180fac9972029066f90a","analyzedAt":"2026-09-05T10:57:22.766Z","contentChangedAt":"2026-09-05T10:57:22.766Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}