{"record":{"id":"e964768dd55d7826","repo":"openai/codex","slug":"environment-variable-env-var-name-is-not-set","errorCode":null,"errorMessage":"environment variable `{env_var_name}` is not set","messagePattern":"environment variable `(.+?)` is not set","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"codex-rs/cli/src/main.rs","lineNumber":2547,"sourceCode":"}\n\nasync fn print_app_server_remote_control_output(\n    mode: AppServerRemoteControlMode,\n) -> anyhow::Result<()> {\n    let output = codex_app_server_daemon::set_remote_control(mode).await?;\n    println!(\"{}\", serde_json::to_string(&output)?);\n    Ok(())\n}\n\nfn read_remote_auth_token_from_env_var_with<F>(\n    env_var_name: &str,\n    get_var: F,\n) -> anyhow::Result<String>\nwhere\n    F: FnOnce(&str) -> Result<String, std::env::VarError>,\n{\n    let auth_token = get_var(env_var_name)\n        .map_err(|_| anyhow::anyhow!(\"environment variable `{env_var_name}` is not set\"))?;\n    let auth_token = auth_token.trim().to_string();\n    if auth_token.is_empty() {\n        anyhow::bail!(\"environment variable `{env_var_name}` is empty\");\n    }\n    Ok(auth_token)\n}\n\nfn read_remote_auth_token_from_env_var(env_var_name: &str) -> anyhow::Result<String> {\n    read_remote_auth_token_from_env_var_with(env_var_name, |name| std::env::var(name))\n}\n\nasync fn run_interactive_tui(\n    mut interactive: TuiCli,\n    remote: Option<String>,\n    remote_auth_token_env: Option<String>,\n    arg0_paths: Arg0DispatchPaths,\n) -> std::io::Result<AppExitInfo> {\n    if let Some(prompt) = interactive.prompt.take() {","sourceCodeStart":2529,"sourceCodeEnd":2565,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/cli/src/main.rs#L2529-L2565","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Export the variable in the same shell (`export CODEX_REMOTE_TOKEN=...`) and rerun codex.","Verify presence first: `printenv CODEX_REMOTE_TOKEN`.","Check spelling on both sides — the flag takes the variable NAME, not the token value.","For service managers, add the variable via Environment= or EnvironmentFile= in the unit."],"exampleFix":"# before\n$ codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN\nerror: environment variable `CODEX_REMOTE_TOKEN` is not set\n# after\n$ export CODEX_REMOTE_TOKEN=<token>\n$ codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN","handlingStrategy":"validation","validationCode":"VAR=CODEX_REMOTE_TOKEN\nif [[ -z ${!VAR+x} ]]; then echo \"error: $VAR is not set\" >&2; exit 2; fi\nif [[ -z ${!VAR//[[:space:]]/} ]]; then echo \"error: $VAR is empty/blank\" >&2; exit 2; fi\ncodex --remote wss://exec.example.com --remote-auth-token-env \"$VAR\"","typeGuard":null,"tryCatchPattern":"if ! codex --remote wss://host --remote-auth-token-env CODEX_REMOTE_TOKEN 2>err.log; then\n  grep -q 'environment variable `CODEX_REMOTE_TOKEN` is not set' err.log && exit 2   # fix the env; do not blind-retry\n  exit 1\nfi","preventionTips":["Guard at script entry: : \"${CODEX_REMOTE_TOKEN:?must be set}\"","Source the .env/rc file that defines the token in the same step that runs codex","Record the variable name next to the --remote-auth-token-env flag in runbooks so they never drift"],"tags":["cli","codex","environment-variable","auth-token","remote"],"backgroundTag":"missing-env-var","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}