astrid-runtime/astrid · error

protocol mismatch: expected , received

Error message

{provider_name} protocol mismatch: expected {}, received {}

What it means

validate_response checks that the provider's reply carries STORAGE_PROVIDER_PROTOCOL_V1 before inspecting anything else. A mismatch means the installed provider binary speaks a different protocol version than the CLI expects, so the response is rejected to prevent misinterpreting fields. This guards the CLI/provider contract across upgrades.

Solutions

  1. Upgrade or downgrade the provider binary so its protocol version matches the CLI's STORAGE_PROVIDER_PROTOCOL_V1.
  2. Reinstall CLI and providers together from the same release so versions stay in lockstep.
  3. If you own the provider, set protocol_version = STORAGE_PROVIDER_PROTOCOL_V1 in the response and re-release.

Example fix

// before (provider)
StorageProviderResponseV1 { protocol_version: 2, .. }

// after (provider)
StorageProviderResponseV1 { protocol_version: STORAGE_PROVIDER_PROTOCOL_V1, .. }
# or: upgrade the astrid-cli/provider pair to matching versions
Defensive patterns

Strategy: validation

Validate before calling

let v = provider_protocol_version(provider_path)?; // ask provider its version up front
if v != STORAGE_PROVIDER_PROTOCOL_V1 {
    eprintln!("provider protocol {v} != required {STORAGE_PROVIDER_PROTOCOL_V1}; upgrade it");
}

Try / catch

match run_storage_command(args).await {
    Err(e) if e.to_string().contains("protocol mismatch") => {
        eprintln!("Reinstall the provider from the same release as the CLI.");
    }
    other => other?,
}

Prevention

When it happens

Trigger: Running a native storage provider built against a different protocol version (older provider after CLI upgrade, or newer provider with an older CLI); a provider that hardcodes the wrong version constant in StorageProviderResponseV1.

Common situations: Partially upgraded deployments where the CLI and the provider plugin come from different releases; hand-rolled providers that forgot to bump/set protocol_version; mixing distro-packaged providers with a cargo-installed CLI.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/52e8143498cc55bc. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/storage.rs:216

            vec![StorageProviderCapabilityV1::Lifecycle],
        ),
        StorageCommand::Unmount(args) => (
            StorageProviderOperationV1::Unmount {
                selector: StorageMountSelectorV1::NativePath(args.mountpoint),
            },
            vec![StorageProviderCapabilityV1::Lifecycle],
        ),
    })
}

fn validate_response(
    provider_name: &str,
    request: &StorageProviderRequestV1,
    response: &StorageProviderResponseV1,
    required_capabilities: &[StorageProviderCapabilityV1],
) -> Result<()> {
    if response.protocol_version != STORAGE_PROVIDER_PROTOCOL_V1 {
        bail!(
            "{provider_name} protocol mismatch: expected {}, received {}",
            STORAGE_PROVIDER_PROTOCOL_V1,
            response.protocol_version
        );
    }
    if response.request_id != request.request_id {
        bail!("{provider_name} returned a response for a different request");
    }
    if response.provider.name != provider_name
        || response.provider.version.is_empty()
        || response.provider.version.len() > 128
        || response.provider.version.chars().any(char::is_control)
        || response.provider.capabilities.len() > 16
        || !capabilities_are_unique(&response.provider.capabilities)
    {
        bail!("native provider identity does not match the co-installed executable");
    }
    for capability in required_capabilities {

View on GitHub (pinned to affd8760f4)