xai-org/grok-build · error

Invalid header: '{header}'. Header name cannot be empty.

Error message

Invalid header: '{header}'. Header name cannot be empty.

What it means

After splitting a --header value on the first colon, the header name is trimmed; if it is empty (e.g. the string starts with ':') the header is rejected because an HTTP header must have a non-empty name.

Source

Thrown at crates/codegen/xai-grok-pager/src/mcp_cmd.rs:458

                env.insert(key.to_string(), value.to_string());
            }
            _ => bail!(
                "Invalid environment variable format: '{pair}'. Environment variables should be added as: -e KEY1=value1 -e KEY2=value2"
            ),
        }
    }
    Ok(env)
}

fn parse_headers(headers: &[String]) -> Result<HashMap<String, String>> {
    let mut parsed = HashMap::new();
    for header in headers {
        let Some((name, value)) = header.split_once(':') else {
            bail!("Invalid header format: '{header}'. Expected format: 'Name: value'");
        };
        let name = name.trim();
        if name.is_empty() {
            bail!("Invalid header: '{header}'. Header name cannot be empty.");
        }
        parsed.insert(name.to_string(), value.trim().to_string());
    }
    Ok(parsed)
}

fn looks_like_url(command: &str) -> bool {
    command.starts_with("http://")
        || command.starts_with("https://")
        || command.starts_with("localhost")
}

/// True for `KEY=value` shapes with a `[A-Za-z_][A-Za-z0-9_]*` key.
fn looks_like_env_pair(s: &str) -> bool {
    let Some((key, _)) = s.split_once('=') else {
        return false;
    };
    let mut chars = key.chars();

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Provide a non-empty header name before the colon.
2. Verify templated header names actually expand (e.g. ${H} is set).
3. Remove the empty header flag entirely if it is not needed.

Example fix

// before
grok mcp add acme --transport http https://acme.example.com/mcp --header ': secret'
// after
grok mcp add acme --transport http https://acme.example.com/mcp --header 'X-Api-Key: secret'

for h in headers {
    let name = h.split_once(':').map(|(n, _)| n.trim()).unwrap_or("");
    assert!(!name.is_empty(), "header '{h}' has an empty name");
}

When it happens

Trigger: `--header ': somevalue'` or `--header ':'` — a colon is present but everything before it is empty or whitespace only.

Common situations: Accidentally deleting the header name while editing a command, template variables that expanded to an empty name (`--header '${H}: v'` with H unset).

Related errors

• --header can only be used with HTTP or SSE servers.
• A URL is required for {label} servers. Usage: grok mcp add -
• Invalid URL '{url}'. Server URLs must start with http:// or
• Unexpected arguments after the URL: '{args}'. HTTP and SSE s
• Invalid name '{name}'. Names can only contain letters, numbe

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/fa33498bf28477f3. Report an issue: GitHub.