warpdotdev/warp · error · anyhow::Error

MCP server '{name}' field 'warp_id' must be a UUID

Error message

MCP server '{name}' field 'warp_id' must be a UUID

What it means

Thrown when an MCP server entry has a `warp_id` field that fails Uuid::parse_str and the WellKnownMcpIds feature flag is disabled. warp_id is the mechanism for referencing a Warp-registered MCP server by UUID; when the flag is off, only strict UUIDs are accepted and anything else is a config error.

Source

Thrown at app/src/ai/agent_sdk/config_file.rs:126

///   the server owns the set of recognized ids and unknown ids are skipped at resolution.
/// - Entries with `command`/`url` remain as inline JSON (`MCPSpec::Json`) containing the unwrapped server map.
pub fn mcp_specs_from_mcp_servers(
    mcp_servers: &Map<String, Value>,
) -> anyhow::Result<Vec<MCPSpec>> {
    let mut uuids: Vec<uuid::Uuid> = Vec::new();
    let mut well_known: Vec<String> = Vec::new();
    let mut json_map: Map<String, Value> = Map::new();

    for (name, config) in mcp_servers {
        let obj = config
            .as_object()
            .ok_or_else(|| anyhow::anyhow!("MCP server '{name}' config must be a JSON object"))?;

        if let Some(warp_id) = obj.get("warp_id").and_then(Value::as_str) {
            if let Ok(uuid) = uuid::Uuid::parse_str(warp_id) {
                uuids.push(uuid);
            } else if !FeatureFlag::WellKnownMcpIds.is_enabled() {
                return Err(anyhow::anyhow!(
                    "MCP server '{name}' field 'warp_id' must be a UUID"
                ));
            } else if warp_id.trim().is_empty() {
                return Err(anyhow::anyhow!(
                    "MCP server '{name}' field 'warp_id' must be non-empty"
                ));
            } else {
                well_known.push(warp_id.to_string());
            }
        } else {
            json_map.insert(name.clone(), config.clone());
        }
    }

    uuids.sort();
    uuids.dedup();
    well_known.sort();
    well_known.dedup();

View on GitHub (pinned to e72fd7aacb)

Solutions

  1. Replace the warp_id value with the server's full UUID from `warp mcp list` (or wherever the registered id is shown).
  2. If you meant an inline server, remove warp_id and specify command/url fields instead — entries without warp_id stay inline JSON.
  3. If you intended a well-known slug, run a build where the WellKnownMcpIds feature flag is enabled.

Example fix

// before
"mcp_servers": { "websearch": { "warp_id": "websearch" } }

// after
"mcp_servers": { "websearch": { "warp_id": "7f2d0e4a-1b9c-4f5e-9a2b-3c8d6e1f0a55" } }
Defensive patterns

Strategy: validation

Validate before calling

if let Some(warp_id) = obj.get("warp_id").and_then(Value::as_str) {
    if uuid::Uuid::parse_str(warp_id).is_err() && !FeatureFlag::WellKnownMcpIds.is_enabled() {
        anyhow::bail!("warp_id '{warp_id}' is not a UUID and well-known ids are disabled");
    }
}

Type guard

fn is_uuid(s: &str) -> bool {
    uuid::Uuid::parse_str(s).is_ok()
}

Try / catch

let specs = mcp_specs_from_mcp_servers(&mcp_servers).map_err(|err| {
    if err.to_string().contains("must be a UUID") {
        user_friendly_config_error(err) // 'fix warp_id or remove it for inline config'
    } else { err }
})?;

Prevention

When it happens

Trigger: A config entry like {"my-server": {"warp_id": "github"}} or a mistyped/copy-truncated UUID ("550e8400-e29b-..."), parsed while FeatureFlag::WellKnownMcpIds is not enabled — the parse fails and the flag check routes it to this error instead of the well-known bucket.

Common situations: Users writing human-readable server slugs into warp_id expecting them to resolve; configs produced for a newer Warp build (where well-known ids exist) run on an older build without the flag; or copy/paste losing UUID characters.

Related errors

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