xai-org/grok-build · error

Leader does not advertise capabilities (legacy version)

Error message

Leader does not advertise capabilities (legacy version)

What it means

ensure_control_caps requires the leader registration to include leader_capabilities; a leader from a legacy (older) build omits that field, so the capability negotiation cannot proceed and this error is raised. It is a forward-compatibility guard, not a runtime fault.

Source

Thrown at crates/codegen/xai-grok-pager-bin/src/main.rs:445

        "wsUrlSuffix": d.ws_url_suffix,
    })
}
fn leader_info_json(
    d: &LeaderDescriptor,
    reg: &LeaderRegistration,
    info: Option<&xai_grok_shell::leader::ControlPayload>,
) -> Result<serde_json::Value> {
    let mut val = leader_descriptor_json(d);
    val["clientId"] = serde_json::json!(reg.client_id);
    if let Some(info) = info {
        val["info"] = serde_json::to_value(info)?;
    }
    Ok(val)
}
fn ensure_control_caps(reg: &LeaderRegistration) -> Result<&LeaderCapabilities> {
    reg.leader_capabilities
        .as_ref()
        .ok_or_else(|| anyhow::anyhow!("Leader does not advertise capabilities (legacy version)"))
}
/// Env override for the `grok workspace` gate: any truthy value enables the
/// command locally, a falsy one disables it — bypassing the remote settings flag.
const WORKSPACE_COMMAND_ENV: &str = "GROK_WORKSPACE_COMMAND";
/// Resolution of the `grok workspace` gate. `Unknown` is kept separate from
/// `Disabled` so we don't tell the user the flag is off when the settings were
/// simply never read (both fail closed, but `Unknown` earns an honest message).
#[derive(Debug, PartialEq, Eq)]
enum WorkspaceGate {
    Enabled,
    Disabled,
    Unknown,
}
/// The `GROK_WORKSPACE_COMMAND` override, if set (`Some(true)`/`Some(false)`);
/// `None` defers to the remote settings flag.
fn workspace_command_env_override() -> Option<bool> {
    std::env::var(WORKSPACE_COMMAND_ENV)
        .ok()

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Restart the leader with an up-to-date grok build that advertises leader_capabilities
2. Kill stale leader processes from older versions and start a fresh session
3. Align versions of the pager CLI and the leader so both speak the capabilities protocol

Example fix

// before
$ grok workspace status   # old leader binary from v1.2 still running
// after
$ pkill -f old-grok-leader && grok workspace start   # fresh, current-version leader

fn leader_supports_caps(reg: &LeaderRegistration) -> bool {
    reg.leader_capabilities.is_some()
}
if !leader_supports_caps(reg) {
    eprintln!("leader is a legacy build; restart with a current grok version");
}

fn has_capabilities(reg: &LeaderRegistration) -> bool {
    reg.leader_capabilities.is_some()
}

match ensure_control_caps(reg) {
    Ok(caps) => { /* proceed with caps */ }
    Err(e) if e.to_string().contains("legacy version") => {
        eprintln!("leader too old: {e}. Restart the leader with an updated grok binary.");
        return Err(e);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling ensure_control_caps (via run_leader_mgmt or ensure_workspace_caps) on a LeaderRegistration whose leader_capabilities field is None — i.e. the running leader predates the capabilities-advertisement protocol.

Common situations: Mixed-version setup: an old grok binary still running as leader while the pager/CLI was updated; leader started before a version upgrade and never restarted.

Related errors

• {}
• resolved leader target did not include a socket path
• no running leader for this environment ({e}). Start a grok s
• Unsupported checkpoint schema version {schema_version}. Cann
• unsupported version: {}

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