{"record":{"id":"11e76258f66e44a2","repo":"warpdotdev/warp","slug":"missing-or-empty-environment-variable-var-name","errorCode":null,"errorMessage":"Missing or empty environment variable: {var_name}","messagePattern":"Missing or empty environment variable: (.+?)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"app/src/ai/mcp/file_mcp_watcher.rs","lineNumber":666,"sourceCode":"        results.into_iter()\n    })\n}\n\n/// Substitutes environment variables in the format ${VAR_NAME} in the given JSON string.\n/// Returns an error if any environment variable is not found, as the server cannot be started.\nfn substitute_env_vars(json_content: &str) -> Result<String, anyhow::Error> {\n    let mut result = json_content.to_string();\n\n    for capture in ENV_VAR_REGEX.captures_iter(json_content) {\n        if let Some(var_match) = capture.get(1) {\n            let var_name = var_match.as_str();\n            match std::env::var(var_name) {\n                Ok(value) if !value.is_empty() => {\n                    let placeholder = format!(\"${{{}}}\", var_name);\n                    result = result.replace(&placeholder, &value);\n                }\n                _ => {\n                    return Err(anyhow::anyhow!(\n                        \"Missing or empty environment variable: {var_name}\"\n                    ));\n                }\n            }\n        }\n    }\n\n    Ok(result)\n}\n\n#[derive(Clone, Copy, Debug, Eq, PartialEq)]\npub enum FileMCPConfigDiagnosticKind {\n    Read,\n    Parse,\n    MissingEnvironmentVariable,\n}\n\n#[derive(Clone, Debug, Eq, PartialEq)]","sourceCodeStart":648,"sourceCodeEnd":684,"githubUrl":"https://github.com/warpdotdev/warp/blob/e72fd7aacbbb2236d9b3be2aad7e7178fe94b4bc/app/src/ai/mcp/file_mcp_watcher.rs#L648-L684","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Check the exact spelling of the variable name inside ${...} against your environment","Ensure the value is non-empty — an empty string is rejected the same as unset","Alternatively hardcode the value or remove the placeholder for that server"],"exampleFix":"# before: config references a var GUI-launched Warp never sees\n{ \"mcpServers\": { \"fetch\": { \"env\": { \"API_KEY\": \"${API_KEY}\" } } } }\n\n# after: make it visible to the GUI environment (macOS), then restart Warp\nlaunchctl setenv API_KEY \"sk-...\"\n# or launch Warp from a shell where API_KEY is exported","handlingStrategy":"validation","validationCode":"// Verify every ${VAR} placeholder resolves before using the config.\nfor name in extract_env_var_names(&json_content) {\n    let value = std::env::var(&name).unwrap_or_default();\n    anyhow::ensure!(!value.is_empty(), \"Missing or empty environment variable: {name}\");\n}","typeGuard":"fn all_env_vars_present(json_content: &str) -> bool {\n    ENV_VAR_REGEX.captures_iter(json_content).all(|c| {\n        c.get(1)\n            .map(|m| !std::env::var(m.as_str()).unwrap_or_default().is_empty())\n            .unwrap_or(true)\n    })\n}","tryCatchPattern":null,"preventionTips":["Launch Warp from a login shell or set required vars via launchctl/systemd user environment so GUI launches see them","Document required variables next to each MCP server config","Treat empty-string values as missing when templating configs"],"tags":["mcp","config","environment","env-vars","setup"],"backgroundTag":null,"analyzedSha":"e72fd7aacbbb2236d9b3be2aad7e7178fe94b4bc","analyzedAt":"2026-08-16T08:27:25.381Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}