astrid-runtime/astrid · error

WinFsp service parent start identity is required on Windows

Error message

WinFsp service parent start identity is required on Windows

What it means

On Windows this provider requires the launching parent to declare a start_identity in the service launch descriptor. If launch.parent.start_identity is None (the field was omitted or explicitly null), validate_service_launch bails before any mount work. The identity anchors the mount to the principal that started it, so an absent value means the launch cannot be attributed and is rejected by design.

Source

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

    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");
    }
    let lease = &launch.lease;
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .context("read system clock")?
        .as_secs();
    if lease.expires_at_epoch_secs < now {
        bail!("WinFsp lease is expired");
    }
    if lease.lease_token.len() < 16 || lease.lease_token.len() > 4096 {
        bail!("WinFsp lease callback token is invalid");
    }
    if !lease.resource_path.is_absolute()
        || !lease.callback_path.is_absolute()
        || lease.callback_path != lease.resource_path.join("control.endpoint")
    {
        bail!("WinFsp lease paths are malformed");
    }

View on GitHub (pinned to affd8760f4)

Solutions

1. Populate parent.start_identity in the launching parent before spawning service_main (e.g. the owning user/account or session identifier).
2. Check the deserialization of the launch JSON on the service side — make sure the field is present and not null; a field silently defaulting to None usually means the key is missing in the file.
3. If this appears after a provider upgrade, regenerate the launch descriptor with the current launcher instead of reusing a cached/older one.
4. Guard shared launcher code so the Windows path always sets start_identity (cfg-gate if other platforms treat it as optional).

Example fix

// before
let launch = StorageProviderServiceLaunchV1 { parent: Parent { pid, token, ..Default::default() }, .. };
// after
let launch = StorageProviderServiceLaunchV1 { parent: Parent { pid, token, start_identity: Some(whoami_identity()), .. }, .. };

if launch.parent.start_identity.is_none() {
    return Err(anyhow!("launch descriptor must set parent.start_identity before starting the Windows service"));
}

fn has_start_identity(p: &Parent) -> bool { p.start_identity.as_deref().map_or(false, |s| !s.is_empty()) }

When it happens

Trigger: service_main -> validate_service_launch with launch.parent.start_identity == None: the parent process built StorageProviderServiceLaunchV1 without populating parent.start_identity, or deserialized a launch JSON that omits/nulls the field.

Common situations: A launcher written against an older schema version (before start_identity became required on Windows) still emits old launch files; hand-written or copied launch JSON omits the field; shared cross-platform launcher code sets the field only on non-Windows targets.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• WinFsp daemon lease contains a relative endpoint
• WinFsp service parent PID is invalid
• WinFsp service parent token is invalid
• WinFsp service parent start identity is invalid
• the WinFsp provider is available only on Windows

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