What causes "environment variable %q not set" in dagger/dagger?

Export the variable in the shell session before calling `.printenv` (export NAME=...)

environment variable %q not set

Error message

environment variable %q not set

What it means

The shell's `.printenv <name>` builtin reads the variable from the interpreter's environment (`hc.Env.Get(name)`); if `v.IsSet()` is false it throws this error. It mirrors POSIX `printenv` semantics: only set variables can be printed.

Source

Thrown at internal/cmd/dagger/shell_commands.go:729

			State: NoState,
			Run: func(ctx context.Context, cmd *ShellCommand, args []string, _ *ShellState) error {
				hc := interp.HandlerCtx(ctx)

				if len(args) == 0 {
					// Print all environment variables
					for name, vr := range hc.Env.Each {
						fmt.Fprintf(hc.Stdout, "%s=%s\n", name, vr)
					}

					return nil
				}

				// Print a specific environment variable
				name := args[0]

				v := hc.Env.Get(name)
				if !v.IsSet() {
					return fmt.Errorf("environment variable %q not set", name)
				}

				return h.Print(ctx, v.String())
			},
		},
		&ShellCommand{
			Use: ".wait [id...]",
			Description: `Wait for background processes to complete

'id' is the process or job ID. If no ID is specified, .wait always returns 0 (zero).
Otherwise, it returns the exit status of the first command that failed. When multiple
processes are given, the command waits for all processes to complete.

Example:

  container | from alpine | with-exec false | stdout &
  job1=$!
  .echo "job id: $job1"

View on GitHub (pinned to 82ba2681db)

Solutions

Export the variable in the shell session before calling `.printenv` (export NAME=...)
Run `.printenv` with no args to list all set variables and confirm the exact name
Check casing/spelling of the variable name

Example fix

# before
> .printenv API_TOKEN
environment variable "API_TOKEN" not set
# after
> export API_TOKEN=xxx
> .printenv API_TOKEN

Defensive patterns

Strategy: validation

Validate before calling

# check before printing
.printenv             # list all set vars
.test -n "$API_TOKEN" && .printenv API_TOKEN

Prevention

Export needed vars in the shell session before use
Remember container env vars are not host shell env vars
Watch case sensitivity of variable names

When it happens

Trigger: `.printenv NAME` where NAME is not present in the shell session's environment — never exported, misspelled, or defined only inside containers rather than the host shell session.

Common situations: Referencing an env var that exists in .env files not loaded into the shell session; expecting container-level env (`with-env-variable`) to be visible to the host shell; case-sensitivity mistakes (PATH vs Path).

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

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/44249a2f93c55493. Report an issue: GitHub.