a persistent volume does not exists for

Error message

a persistent volume does not exists for `{0}`, but there is a volume for a different version.
 > Create a new volume with `cross-util volumes create --toolchain {0}`

What it means

In remote mode, cross can reuse a persistent toolchain volume. run() lists existing volumes: if the exact versioned toolchain volume is missing but another volume sharing the toolchain prefix exists (a different cross/toolchain version), it warns and points to `cross-util volumes create --toolchain`, then proceeds with a discarded (temporary) volume.

Solutions

Run `cross-util volumes create --toolchain <toolchain>` to create the matching persistent volume, as the message suggests.
Remove stale volumes from old versions (`cross-util volumes remove` or `docker volume rm`) to avoid confusion.
Pin the cross version in CI so the versioned volume name stays consistent across runs.

Example fix

# before
cross build --remote --target aarch64-unknown-linux-gnu
# warns: volume for different version

# after
cross-util volumes create --toolchain aarch64-unknown-linux-gnu
cross build --remote --target aarch64-unknown-linux-gnu

Defensive patterns

Strategy: validation

Validate before calling

# Ensure the exact toolchain volume exists before a remote build
prefix="cross-dev-tools-<toolchain>"
docker volume ls --format '{{.Name}}' | grep -Fx "$prefix-<version>" \
  || { echo "creating toolchain volume"; cross-util volumes create --toolchain <toolchain>; }

Prevention

Create toolchain volumes explicitly with cross-util after upgrading cross
Pin the cross version in CI to keep volume names stable
Prune volumes from old toolchain versions

When it happens

Trigger: run() in remote mode when DockerVolume::existing returns no volume equal to toolchain_id but at least one volume starts with VOLUME_PREFIX + toolchain name (built with an older/newer cross or toolchain version).

Common situations: After upgrading cross or the Rust toolchain while keeping old volumes; switching between cross versions in CI causing versioned volume name mismatches.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/9acf8cca1264f53d. Report an issue: GitHub.

Appendix: source

Thrown at src/docker/remote.rs:792

    // 8. stop container and delete data volume
    //
    // we use structs that wrap the resources to ensure they're dropped
    // in the correct order even on error, to ensure safe cleanup

    // 1. get our unique identifiers and cleanup from a previous run.
    // this can happen if we didn't gracefully exit before
    // note that since we use `docker run --rm`, it's very
    // unlikely the container state existed before.
    let toolchain_id = toolchain_dirs.unique_toolchain_identifier()?;
    let container_id = toolchain_dirs.unique_container_identifier(target.target())?;
    let volume = {
        let existing = DockerVolume::existing(engine, toolchain_dirs.toolchain(), msg_info)?;
        if existing.iter().any(|v| v == &toolchain_id) {
            VolumeId::Keep(toolchain_id)
        } else {
            let partial = format!("{VOLUME_PREFIX}{}", toolchain_dirs.toolchain());
            if existing.iter().any(|v| v.starts_with(&partial)) {
                msg_info.warn(format_args!(
                    "a persistent volume does not exists for `{0}`, but there is a volume for a different version.\n > Create a new volume with `cross-util volumes create --toolchain {0}`",
                    toolchain_dirs.toolchain()
                ))?;
            }
            VolumeId::Discard
        }
    };

    let container = DockerContainer::new(engine, &container_id);
    let state = container.state(msg_info)?;
    if !state.is_stopped() {
        msg_info.warn(format_args!("container {container_id} was running."))?;
        container.stop_default(msg_info)?;
    }
    if state.exists() {
        msg_info.warn(format_args!("container {container_id} was exited."))?;
        container.remove(msg_info)?;
    }

View on GitHub (pinned to 8c1a8aa4b6)