What causes "remote cache action bytes do not match cache key" in jdx/mise?

Recompute the key as CacheDigest::blake3(action).hash immediately before calling commit and pass that value

remote cache action bytes do not match cache key

Error message

remote cache action bytes do not match cache key

What it means

During commit, the blake3 digest of the supplied action bytes did not equal the cache key they are being stored under. Cache keys are derived from action content, so a mismatch means the key and payload are inconsistent and the entry would be unretrievable (or would alias another action); the library rejects the write.

Source

Thrown at src/task/task_cache_store.rs:449

        let nonce = crate::rand::random_string(8);
        Ok(TaskCacheStoreWrite {
            artifact_path: self.staging_dir.join(format!("{key}.part-{nonce}.tar.zst")),
            manifest_path: self.staging_dir.join(format!("{key}.part-{nonce}.json")),
        })
    }

    async fn commit(
        &self,
        key: &str,
        action: &[u8],
        write: &TaskCacheStoreWrite,
        manifest: &[u8],
        has_artifact: bool,
    ) -> Result<()> {
        validate_remote_key(key)?;
        let action_digest = CacheDigest::blake3(action);
        if action_digest.hash != key {
            bail!("remote cache action bytes do not match cache key");
        }
        let manifest: CacheManifest = serde_json::from_slice(manifest)?;
        if manifest.key != key {
            bail!("local task cache manifest does not match remote action");
        }
        let metadata = canonical_json(&serde_json::to_value(
            RemoteClientMetadata::from_manifest(&manifest),
        )?)?;
        let mut uploads = vec![
            BlobUpload {
                digest: action_digest.clone(),
                source: BlobSource::Bytes(action.to_vec()),
            },
            BlobUpload {
                digest: CacheDigest::blake3(&metadata),
                source: BlobSource::Bytes(metadata),
            },
        ];

View on GitHub (pinned to afd2eddd3a)

Solutions

Recompute the key as CacheDigest::blake3(action).hash immediately before calling commit and pass that value
Never mutate the action buffer after deriving its key
Ensure the same canonical serialization is used for both key derivation and the bytes passed to commit
Log both key and digest on mismatch to identify which side is stale

Example fix

// before
let key = old_key;
action.inputs.push(extra_input); // action mutated after key derivation
store.commit(&key, &action, &manifest, true)?;
// after
let key = CacheDigest::blake3(&action).hash;
store.commit(&key, &action, &manifest, true)?;

Defensive patterns

Strategy: validation

Validate before calling

fn assert_key_matches(key: &CacheKey, action: &[u8]) -> anyhow::Result<()> {
    let digest = CacheDigest::blake3(action);
    anyhow::ensure!(digest.hash == *key, "key {} != action digest {}", key, digest.hash);
    Ok(())
}
// call immediately before store.commit(&key, &action, ...)

Try / catch

if let Err(e) = store.commit(&key, &action, &manifest_bytes, has_artifact).await {
    if e.to_string().contains("do not match cache key") {
        let key = CacheDigest::blake3(&action).hash;
        return store.commit(&key, &action, &manifest_bytes, has_artifact).await;
    }
    return Err(e);
}

Prevention

Derive the key from the exact bytes passed to commit, at the last moment
Never mutate action buffers after key derivation
Use one shared helper for key computation across all commit call sites

When it happens

Trigger: Calling commit() with a key computed from a different action serialization than the `action` argument — e.g. keying on a pre-canonicalization action buffer, mutating the action after key derivation, or copying a key from another entry.

Common situations: Custom cache tooling computing keys with a different hashing/serialization than CacheDigest::blake3; refactoring that changes action bytes without recomputing the key; reusing stale keys after retrying with modified task inputs.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/d1283fd4b4a3c28e. Report an issue: GitHub.