jdx/mise · error

unsupported remote cache directory version

Error message

unsupported remote cache directory version

What it means

Every RemoteDirectory proto carries a version field and this mise restores only version 1. A directory blob with any other version bails with 'unsupported remote cache directory version' before any node of the restore tree is created.

Source

Thrown at src/task/task_cache_store.rs:723

}

async fn materialize_remote_tree(
    store: &HttpTaskCacheStore,
    root: &CacheDigest,
) -> Result<tempfile::NamedTempFile> {
    let mut pending = vec![(PathBuf::new(), root.clone(), BTreeSet::new())];
    let mut nodes = BTreeMap::<PathBuf, RestoredNode>::new();
    while let Some((path, digest, mut ancestors)) = pending.pop() {
        if !ancestors.insert(digest.clone()) {
            bail!("remote cache directory graph contains a cycle");
        }
        let bytes = store.client.get_blob(&digest, DIRECTORY_MEDIA_TYPE).await?;
        let directory: RemoteDirectory = serde_json::from_slice(&bytes)?;
        if canonical_json(&serde_json::to_value(&directory)?)? != bytes {
            bail!("remote cache directory is not canonical JSON");
        }
        if directory.version != 1 {
            bail!("unsupported remote cache directory version");
        }
        let mut names = BTreeSet::new();
        for directory in directory.directories {
            validate_cache_name(&directory.name)?;
            if !names.insert(directory.name.clone()) {
                bail!("remote cache directory contains duplicate names");
            }
            let child = path.join(&directory.name);
            validate_cache_path(&child)?;
            nodes.insert(
                child.clone(),
                RestoredNode::Directory {
                    mode: directory.mode,
                },
            );
            pending.push((child, directory.digest, ancestors.clone()));
        }
        for file in directory.files {

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Upgrade mise to at least the version that wrote the cache (mise use -g mise@<version>)
2. Or clear the remote cache entries and repopulate with the current version
3. Pin one mise version for all CI cache writers and readers

// if you cache RemoteDirectory protos yourself, check before restore:
let dir: RemoteDirectory = serde_json::from_slice(&bytes)?;
if dir.version != 1 {
    return Ok(None); // treat as a miss and rebuild
}

fn directory_version_supported(bytes: &[u8]) -> Option<bool> {
    serde_json::from_slice::<RemoteDirectory>(bytes)
        .ok()
        .map(|d| d.version == 1)
}

match restore_from_remote(&key).await {
    Ok(hit) => hit,
    Err(err) if err.to_string().contains("unsupported remote cache directory version") => {
        warn!("cache entry written by a different mise version; rebuilding");
        purge_action_result(&key).await.ok();
        run_task_uncached(&task).await?
    }
    Err(err) => return Err(err),
}

When it happens

Trigger: materialize_remote_tree fetches a directory proto whose version field is not 1 - cache entries written by a newer mise that bumped the schema, or a hand-crafted blob.

Common situations: Shared CI cache across teams on different mise versions; upgrading mise and restoring entries written by a newer client; rollback after a schema change.

Related errors

• unsupported remote cache client metadata version
• task cache store version mismatch: local version {}, remote
• remote cache metadata kind is not a task
• remote action result is missing its output root
• remote cache path escapes its output root

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/d28796e30a6aee34. Report an issue: GitHub.