openai/codex · error

environment variable `{env_var_name}` is not set

Error message

environment variable `{env_var_name}` is not set

What it means

When the TUI runs in remote mode, `--remote-auth-token-env` names the environment variable that holds the auth token. read_remote_auth_token_from_env_var_with calls get_var (std::env::var at runtime) and maps any VarError to this error before any network connection is attempted. It is a fail-fast guard: the token must already exist in codex's environment.

Source

Thrown at codex-rs/cli/src/main.rs:2547

}

async fn print_app_server_remote_control_output(
    mode: AppServerRemoteControlMode,
) -> anyhow::Result<()> {
    let output = codex_app_server_daemon::set_remote_control(mode).await?;
    println!("{}", serde_json::to_string(&output)?);
    Ok(())
}

fn read_remote_auth_token_from_env_var_with<F>(
    env_var_name: &str,
    get_var: F,
) -> anyhow::Result<String>
where
    F: FnOnce(&str) -> Result<String, std::env::VarError>,
{
    let auth_token = get_var(env_var_name)
        .map_err(|_| anyhow::anyhow!("environment variable `{env_var_name}` is not set"))?;
    let auth_token = auth_token.trim().to_string();
    if auth_token.is_empty() {
        anyhow::bail!("environment variable `{env_var_name}` is empty");
    }
    Ok(auth_token)
}

fn read_remote_auth_token_from_env_var(env_var_name: &str) -> anyhow::Result<String> {
    read_remote_auth_token_from_env_var_with(env_var_name, |name| std::env::var(name))
}

async fn run_interactive_tui(
    mut interactive: TuiCli,
    remote: Option<String>,
    remote_auth_token_env: Option<String>,
    arg0_paths: Arg0DispatchPaths,
) -> std::io::Result<AppExitInfo> {
    if let Some(prompt) = interactive.prompt.take() {

View on GitHub (pinned to 339751715c)

Solutions

1. Export the variable in the same shell (`export CODEX_REMOTE_TOKEN=...`) and rerun codex.
2. Verify presence first: `printenv CODEX_REMOTE_TOKEN`.
3. Check spelling on both sides — the flag takes the variable NAME, not the token value.
4. For service managers, add the variable via Environment= or EnvironmentFile= in the unit.

Example fix

# before
$ codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN
error: environment variable `CODEX_REMOTE_TOKEN` is not set
# after
$ export CODEX_REMOTE_TOKEN=<token>
$ codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN

VAR=CODEX_REMOTE_TOKEN
if [[ -z ${!VAR+x} ]]; then echo "error: $VAR is not set" >&2; exit 2; fi
if [[ -z ${!VAR//[[:space:]]/} ]]; then echo "error: $VAR is empty/blank" >&2; exit 2; fi
codex --remote wss://exec.example.com --remote-auth-token-env "$VAR"

if ! codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN 2>err.log; then
  grep -q 'environment variable `CODEX_REMOTE_TOKEN` is not set' err.log && exit 2   # fix the env; do not blind-retry
  exit 1
fi

When it happens

Trigger: `codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN` when CODEX_REMOTE_TOKEN is not exported in that shell; systemd/launchd units, cron jobs, or container entrypoints where the variable was never added to the environment.

Common situations: Typo in the variable name versus what was exported; token defined in a .env file the shell never sourced; CI where the secret is injected into one step but not the codex step; sudo stripping the environment.

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

• environment variable `{env_var_name}` is empty
• `--remote-auth-token-env` is only supported for interactive
• `--strict-config` is not supported for `codex {subcommand}`
• failed to load marketplace(s): {issue_lines}
• {} upgrade failure(s) occurred.

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/e964768dd55d7826. Report an issue: GitHub.