mikefarah/yq · error

value for env variable '%v' not provided in env()

Error message

value for env variable '%v' not provided in env()

What it means

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.

Source

Thrown at pkg/yqlib/operator_env.go:38

	if ConfiguredSecurityPreferences.DisableEnvOps {
		return Context{}, fmt.Errorf("env operations have been disabled")
	}
	envName := expressionNode.Operation.CandidateNode.Value
	log.Debugf("EnvOperator, env name: %v", envName)

	rawValue := os.Getenv(envName)

	preferences := expressionNode.Operation.Preferences.(envOpPreferences)

	var node *CandidateNode
	if preferences.StringValue {
		node = &CandidateNode{
			Kind:  ScalarNode,
			Tag:   "!!str",
			Value: rawValue,
		}
	} else if rawValue == "" {
		return Context{}, fmt.Errorf("value for env variable '%v' not provided in env()", envName)
	} else {
		decoder := NewYamlDecoder(ConfiguredYamlPreferences)
		if err := decoder.Init(strings.NewReader(rawValue)); err != nil {
			return Context{}, err
		}
		var err error
		node, err = decoder.Decode()

		if err != nil {
			return Context{}, err
		}

	}
	log.Debugf("ENV tag: %v", node.Tag)
	log.Debugf("ENV value: %v", node.Value)
	log.Debugf("ENV Kind: %v", node.Kind)

	return context.SingleChildContext(node), nil

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Export the variable before running yq: export MY_VAR=value
2. Fix typos in the variable name inside the expression
3. Provide a fallback in shell: MY_VAR="${MY_VAR:-default}" yq '.x = env(MY_VAR)'
4. If an empty value is legitimate, use envsubst on a pre-built string or handle emptiness in the shell

Example fix

// before (MY_VAR unset)
yq '.url = env(MY_VAR)' file.yaml
// error: value for env variable 'MY_VAR' not provided in env()

// after
MY_VAR=https://api.example.com yq '.url = env(MY_VAR)' file.yaml

: "${MY_VAR:?MY_VAR must be set and non-empty}" && yq '.x = env(MY_VAR)' file.yaml

def env_or(name, default=None):
    v = os.environ.get(name)
    if not v:
        return default
    return v

out=$(yq '.x = env(MY_VAR)' f.yaml 2>&1) || {
  echo "env var missing: $out" >&2
  exit 2
}

When it happens

Trigger: Evaluating `env(SOME_VAR)` where SOME_VAR is not set in the process environment, or is set to the empty string.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• env operations have been disabled
• cannot substitute with %v, can only substitute strings. Hint
• no support for input format
• aborted
• unrecognised type :( %v

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/49c15290e6e4b49f. Report an issue: GitHub.