Invalid header format: '{header}'. Expected format: 'Name: v

Error message

Invalid header format: '{header}'. Expected format: 'Name: value'

What it means

`parse_headers` requires each --header value to contain a colon separating name and value, i.e. 'Name: value'. A header string without any ':' is rejected with this message. This keeps HTTP headers well-formed before they are attached to an HTTP/SSE server config.

Source

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

    let mut env = HashMap::new();
    for pair in pairs {
        match pair.split_once('=') {
            Some((key, value)) if !key.is_empty() => {
                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 {

View on GitHub (pinned to bc7f02eddd)

Solutions

Use the 'Name: value' format: --header 'Authorization: Bearer <token>'.
Check that the colon survived shell quoting (it is not an = separated pair).
One --header flag per header.

Example fix

// before
grok mcp add acme --transport http https://acme.example.com/mcp --header 'Authorization=Bearer x'
// after
grok mcp add acme --transport http https://acme.example.com/mcp --header 'Authorization: Bearer x'

Defensive patterns

Strategy: validation

Validate before calling

for h in headers {
    assert!(h.contains(':'), "header '{h}' must be 'Name: value'");
}

Type guard

fn is_well_formed_header(h: &str) -> bool { h.split_once(':').map_or(false, |(n, _)| !n.trim().is_empty()) }

Prevention

Use 'Name: value' colon format, not KEY=value.
Quote headers in the shell so the colon survives.
One --header flag per header.

When it happens

Trigger: `--header 'Authorization Bearer x'` (missing colon), passing key=value style pairs instead of Name: value, or shell mangling that drops the colon.

Common situations: Reusing -e KEY=value syntax for headers, copying curl -H examples that used a different format, YAML/JSON-style header definitions pasted into the CLI.

Related errors

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