Hmbown/CodeWhale · error

xAI OAuth refresh failed ({err}). Run `grok login` or device

Error message

xAI OAuth refresh failed ({err}). Run `grok login` or device-code login again. If SuperGrok OAuth returns HTTP 403, use XAI_API_KEY instead.

What it means

Terminal failure of the xAI OAuth refresh-token grant: the token endpoint answered, but with a non-success status or an OAuth error body. Because the request carried a credential, the underlying {err} detail is deliberately not echoed beyond this formatted message. The message also encodes the recovery paths: re-authenticate via `grok login` or device-code login, and notes that SuperGrok OAuth can return HTTP 403 where XAI_API_KEY works.

Source

Thrown at crates/tui/src/xai_oauth.rs:1203

    let params = [
        ("client_id", client_id),
        ("grant_type", "refresh_token"),
        ("refresh_token", refresh_token),
    ];
    #[cfg(test)]
    crate::external_credentials::record_oauth_network();
    let response = client
        .post(token_endpoint)
        .form(&params)
        .send()
        .context("xAI OAuth refresh request failed")?;
    let (status, body): (_, TokenResponse) =
        parse_oauth_json_response(response, "xAI OAuth refresh")?;
    if !status.is_success() || body.error.is_some() {
        // Refresh requests carry a credential. Do not echo a server-provided
        // description that could reflect the submitted refresh token.
        let err = oauth_failure_detail(body.error.as_deref(), None, status);
        bail!(
            "xAI OAuth refresh failed ({err}). Run `grok login` or device-code login again. \
             If SuperGrok OAuth returns HTTP 403, use XAI_API_KEY instead."
        );
    }
    Ok(body)
}

fn request_device_code(
    device_authorization_endpoint: &str,
    client_id: &str,
    scopes: &str,
) -> Result<DeviceCodeGrant> {
    let client = crate::tls::reqwest_blocking_client_builder()
        .timeout(Duration::from_secs(20))
        .build()
        .context("Failed to build xAI device-code client")?;
    let params = [("client_id", client_id), ("scope", scopes)];
    #[cfg(test)]

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Run `grok login` or start device-code login again to obtain fresh tokens
2. If the detail mentions HTTP 403 from SuperGrok OAuth, switch to XAI_API_KEY authentication
3. Check system time skew and network access to the xAI token endpoint, then retry once
4. If the error indicates an invalid_grant, accept that the refresh token expired and simply re-login

When it happens

Trigger: Thrown at crates/tui/src/xai_oauth.rs:1203 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/33c3ae7328f7a642. Report an issue: GitHub.