astrid-runtime/astrid · error

unsupported WinFsp service launch schema

Error message

unsupported WinFsp service launch schema {}

What it means

validate_service_launch rejects a StorageProviderServiceLaunchV1 whose schema field does not equal STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1. The schema constant is a compatibility marker between parent and service; a mismatch means the payload layout may differ in unsafe ways, so the service refuses to interpret it.

Solutions

  1. Ensure the parent and the WinFsp service binary come from the same build/version of the crate
  2. Rebuild/redeploy both components together after any schema change
  3. Fix the schema field in generated or hand-written launch documents to STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1
  4. Check PATH/shadowing: an older service exe may be the one being launched

Example fix

// before
{"schema":"storage.filesystem.service.launch.v0", ...}
// after
{"schema":"storage.filesystem.service.launch.v1", ...}
Defensive patterns

Strategy: validation

Validate before calling

if launch.schema != STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1 {
    return Err(format!("expected schema {}, got {}", STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1, launch.schema));
}

Type guard

fn is_v1_launch(launch: &StorageProviderServiceLaunchV1) -> bool {
    launch.schema == STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1
}

Try / catch

match service_err {
    Err(e) if e.to_string().contains("unsupported") && e.to_string().contains("schema") => {
        eprintln!("version mismatch: align parent and service binaries");
    }
    other => other?,
}

Prevention

When it happens

Trigger: service_main calls validate_service_launch with a launch document whose schema string differs from the compiled-in V1 constant — typically a launch produced by a different version of the crate, or a hand-edited/templated launch file.

Common situations: Mixing versions of astrid-storage-provider-winfsp binaries (old parent, new service); a partial upgrade leaving mismatched binaries on PATH; hand-crafting the launch JSON for testing with the wrong schema string.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at crates/astrid-storage-provider-winfsp/src/win.rs:238

        mount_id: launch.lease.mount_id.as_uuid(),
        control_path: launch.control_path.clone(),
        challenge,
    };
    let mut stdout = std::io::stdout().lock();
    serde_json::to_writer(&mut stdout, &ready).context("encode WinFsp readiness")?;
    stdout
        .write_all(b"\n")
        .context("terminate WinFsp readiness response")?;
    stdout.flush().context("flush WinFsp readiness")?;

    let result = private_service_loop(filesystem, listener, &launch).await;
    let _ = local_transport::remove_endpoint(&launch.control_path);
    result
}

fn validate_service_launch(launch: &StorageProviderServiceLaunchV1) -> Result<()> {
    if launch.schema != STORAGE_FILESYSTEM_SERVICE_LAUNCH_SCHEMA_V1 {
        bail!("unsupported WinFsp service launch schema {}", launch.schema);
    }
    if launch.parent.pid <= 1 || launch.parent.pid == std::process::id() {
        bail!("WinFsp service parent PID is invalid");
    }
    if launch.parent.token.len() < 16
        || launch.parent.token.len() > 512
        || launch.parent.token.chars().any(char::is_control)
    {
        bail!("WinFsp service parent token is invalid");
    }
    if let Some(identity) = launch.parent.start_identity.as_deref()
        && (identity.is_empty() || identity.len() > 512 || identity.chars().any(char::is_control))
    {
        bail!("WinFsp service parent start identity is invalid");
    }
    if launch.parent.start_identity.is_none() {
        bail!("WinFsp service parent start identity is required on Windows");
    }

View on GitHub (pinned to affd8760f4)