xai-org/grok-build · error

no running leader for this environment ({e}). Start a grok s

Error message

no running leader for this environment ({e}). Start a grok session, or run `grok workspace start`.

What it means

connect_workspace_control wraps any failure from LeaderClient::connect in this user-facing message. The leader client could not connect for the given environment (no registered leader, dead socket, refused connection), and the error guides the user to start a session or the workspace explicitly.

Source

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

async fn connect_workspace_control(
    agent_config: &AgentConfig,
    target: &LeaderTargetArgs,
) -> Result<LeaderClient> {
    if target.pid.is_some() {
        let (_descriptor, client) = connect_to_leader(target).await?;
        return Ok(client);
    }
    let ws_url = &agent_config.grok_com_config.grok_ws_url;
    let socket = socket_path_for_ws_url(ws_url);
    LeaderClient::connect(
        socket,
        "grok-workspace-cli",
        ClientMode::Stdio,
        ClientCapabilities::default(),
    )
    .await
    .map_err(|e| {
        anyhow::anyhow!(
            "no running leader for this environment ({e}). \
             Start a grok session, or run `grok workspace start`."
        )
    })
}
#[tracing::instrument(level = "debug", skip_all)]
async fn workspace_control(
    target: &LeaderTargetArgs,
    json: bool,
    command: ControlCommand,
) -> Result<()> {
    let agent_config = xai_grok_shell::config::load_agent_config_disk_only()
        .map_err(|e| anyhow::anyhow!("Failed to create agent config: {e}"))?;
    let client = connect_workspace_control(&agent_config, target).await?;
    ensure_workspace_caps(client.registration())?;
    let payload = client.send_control(command).await??;
    render_workspace_payload(&payload, json);
    client.cancel();

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Start a grok session or run `grok workspace start` to bring up a leader
2. Verify the leader process is alive and its socket file exists at the resolved path
3. Check you are targeting the correct environment (resolve_target args)
4. Remove stale socket files left by a crashed leader and restart

// check a leader is reachable before the workspace command
let path = resolve_socket_for_environment(target)?;
if !path.exists() {
    eprintln!("no leader socket at {}; run `grok workspace start`", path.display());
    std::process::exit(1);
}

fn leader_socket_alive(path: &std::path::Path) -> bool {
    path.exists() // optionally also probe a ping control message
}

match connect_workspace_control(&agent_config, target).await {
    Ok(c) => c,
    Err(e) if e.to_string().contains("no running leader") => {
        eprintln!("{e}"); // message already tells the user what to do
        std::process::exit(2);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling connect_workspace_control when LeaderClient::connect(socket_path, "grok-workspace-cli", Stdio, default caps) fails — typically because no leader is running/registered for the target environment, or the socket exists but refuses connections.

Common situations: Running `grok workspace ...` commands before any grok session started; leader crashed leaving a stale socket file; wrong environment target so resolution points at a nonexistent leader.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• {}
• resolved leader target did not include a socket path
• no target specified
• send failed: {body}
• screen query failed: {body}

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