jdx/mise · error

remote cache capability protocol {} is incompatible with cli

Error message

remote cache capability protocol {} is incompatible with client protocol {PROTOCOL_VERSION}

What it means

Thrown while fetching server capabilities (crates/mise-cache-core/src/lib.rs:533): the server responded 2xx with a RemoteCacheCapabilities JSON whose protocol.major != PROTOCOL_VERSION (currently 1). The client refuses to speak blob-pack protocol with an incompatible major version rather than misinterpret the wire format.

Source

Thrown at crates/mise-cache-core/src/lib.rs:533

            .get_or_try_init(|| async {
                let url = self.capabilities_endpoint()?;
                let response = self
                    .request(reqwest::Method::GET, url, "application/json")
                    .await?
                    .send()
                    .await?;
                if matches!(
                    response.status(),
                    StatusCode::NOT_FOUND
                        | StatusCode::METHOD_NOT_ALLOWED
                        | StatusCode::NOT_IMPLEMENTED
                ) {
                    return Ok(None);
                }
                let capabilities: RemoteCacheCapabilities =
                    response.error_for_status()?.json().await?;
                if capabilities.protocol.major != PROTOCOL_VERSION {
                    bail!(
                        "remote cache capability protocol {} is incompatible with client protocol {PROTOCOL_VERSION}",
                        capabilities.protocol.major
                    );
                }
                if !capabilities.features.blob_packs {
                    return Ok(None);
                }
                let max_items = usize::try_from(capabilities.limits.max_batch_items)
                    .ok()
                    .filter(|limit| *limit > 0)
                    .ok_or_else(|| {
                        eyre!("remote cache blob packs require a positive max_batch_items limit")
                    })?;
                if capabilities.limits.max_pack_bytes == 0 {
                    bail!("remote cache blob packs require a positive max_pack_bytes limit");
                }
                Ok(Some(BlobPackLimits {
                    max_items: max_items.min(MAX_STAGED_BLOB_PACK_ITEMS),

View on GitHub (pinned to 6f52dcdf99)

Solutions

1. Upgrade mise (the client) to a version whose PROTOCOL_VERSION matches the server's advertised major — capabilities JSON shows exactly what the server speaks
2. If you operate the server, pin it to protocol major 1 until all clients are upgraded
3. Check the configured remote cache URL — a wrong base_url can hit an unrelated service whose /capabilities JSON parses but reports a different major
4. If you control both sides temporarily, disable blob packs on the server (features.blob_packs=false makes the client skip the incompatibility path only if the protocol major still matches — for major mismatch you must align versions)

let caps = client.capabilities().await?; // surfaced via the same fetch
if let Some(c) = &caps && c.protocol.major != 1 {
    return Err("server protocol too new; upgrade client or pin server to v1");
}

fn server_is_v1(caps: &RemoteCacheCapabilities) -> bool {
    caps.protocol.major == PROTOCOL_VERSION
}

match client.capabilities().await {
    Err(e) if e.to_string().contains("incompatible with client protocol") => {
        eprintln!("remote cache protocol mismatch — continuing without remote cache");
        None // degrade to local-only caching
    }
    other => other.ok().flatten(),
}

When it happens

Trigger: Any first use of the remote cache that triggers the capabilities fetch (cached in a tokio OnceCell per client): GET v1/capabilities returns e.g. {"protocol":{"major":2,...}} while this client only speaks v1. Happens after upgrading the server but not the client, or pointing the client at a cache server built against a newer protocol.

Common situations: Server upgraded ahead of clients in a shared CI cache fleet; new protocol rollout where major was bumped for an incompatible pack format; pointing MISE remote cache config at a URL served by a different product that happens to respond to /capabilities.

Related errors

• remote cache blob packs require a positive max_pack_bytes li
• action prediction payload is too large
• task action manifest has an invalid identity
• task action manifest contains duplicate predictions
• unsupported remote cache digest algorithm

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/90e25aec71b5c1f9. Report an issue: GitHub.