warpdotdev/warp · error · anyhow::Error

Missing or empty environment variable: {var_name}

Error message

Missing or empty environment variable: {var_name}

What it means

Warp watches MCP provider config files (JSON with `${VAR_NAME}` placeholders) and substitutes environment variables via `substitute_env_vars`. If any referenced variable is unset OR set to an empty string, the entire config is rejected with this error (surfaced as a FileMCPConfigDiagnostic of kind MissingEnvironmentVariable), because the MCP server cannot start with an unresolved placeholder. Substitution is strict: one bad variable fails the whole file.

Source

Thrown at app/src/ai/mcp/file_mcp_watcher.rs:666

        results.into_iter()
    })
}

/// Substitutes environment variables in the format ${VAR_NAME} in the given JSON string.
/// Returns an error if any environment variable is not found, as the server cannot be started.
fn substitute_env_vars(json_content: &str) -> Result<String, anyhow::Error> {
    let mut result = json_content.to_string();

    for capture in ENV_VAR_REGEX.captures_iter(json_content) {
        if let Some(var_match) = capture.get(1) {
            let var_name = var_match.as_str();
            match std::env::var(var_name) {
                Ok(value) if !value.is_empty() => {
                    let placeholder = format!("${{{}}}", var_name);
                    result = result.replace(&placeholder, &value);
                }
                _ => {
                    return Err(anyhow::anyhow!(
                        "Missing or empty environment variable: {var_name}"
                    ));
                }
            }
        }
    }

    Ok(result)
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FileMCPConfigDiagnosticKind {
    Read,
    Parse,
    MissingEnvironmentVariable,
}

#[derive(Clone, Debug, Eq, PartialEq)]

View on GitHub (pinned to e72fd7aacb)

Solutions

1. Export the variable in the environment Warp actually runs with: launch Warp from a shell where it is set, or use `launchctl setenv VAR value` (macOS GUI) / systemd user Environment, then restart Warp
2. Check the exact spelling of the variable name inside ${...} against your environment
3. Ensure the value is non-empty — an empty string is rejected the same as unset
4. Alternatively hardcode the value or remove the placeholder for that server

Example fix

# before: config references a var GUI-launched Warp never sees
{ "mcpServers": { "fetch": { "env": { "API_KEY": "${API_KEY}" } } } }

# after: make it visible to the GUI environment (macOS), then restart Warp
launchctl setenv API_KEY "sk-..."
# or launch Warp from a shell where API_KEY is exported

// Verify every ${VAR} placeholder resolves before using the config.
for name in extract_env_var_names(&json_content) {
    let value = std::env::var(&name).unwrap_or_default();
    anyhow::ensure!(!value.is_empty(), "Missing or empty environment variable: {name}");
}

fn all_env_vars_present(json_content: &str) -> bool {
    ENV_VAR_REGEX.captures_iter(json_content).all(|c| {
        c.get(1)
            .map(|m| !std::env::var(m.as_str()).unwrap_or_default().is_empty())
            .unwrap_or(true)
    })
}

When it happens

Trigger: An MCP server config file contains a `${API_KEY}`-style placeholder and `std::env::var(var_name)` returns Err (unset) or Ok("") — the variable exists in your shell but Warp was launched (e.g. as a GUI app) from an environment that never sourced it, or the value is genuinely empty.

Common situations: macOS GUI launch does not source .zshrc/.bash_profile so the var is missing; CI or container environments without the var; var set to empty string (treated identically to missing); typo in the variable name inside the placeholder.

Related errors

• Failed to parse Codex TOML: {e}
• source_config_unavailable
• config_unavailable
• config_not_regular_file
• config_too_large

AI-assisted analysis of warpdotdev/warp@e72fd7aacb (2026-08-16). Data as JSON: /api/errors/11e76258f66e44a2. Report an issue: GitHub.