What causes "FSKit service control endpoint is already present" in astrid-runtime/astrid?

Stop the existing service instance holding the endpoint, then relaunch

FSKit service control endpoint is already present

Error message

FSKit service control endpoint is already present

What it means

Before binding, validate_control_path checks local_transport::endpoint_is_present on the control path; if a listener/socket already exists there, another service instance is running (or a stale socket remains) and launch is aborted to avoid double-binding.

Solutions

Stop the existing service instance holding the endpoint, then relaunch
Remove the stale socket file if no process is listening
Ensure shutdown paths unbind/unlink the control socket before exit

Example fix

// before
service.launch(&lease)?; // endpoint still bound by old instance
// after
if local_transport::endpoint_is_present(&control_path)? { service.shutdown()?; }
service.launch(&lease)?;

Defensive patterns

Strategy: try-catch

Validate before calling

fn endpoint_free(control: &std::path::Path) -> bool {
    !local_transport::endpoint_is_present(control).unwrap_or(true)
}

Try / catch

match provider.run(launch) {
    Err(e) if e.to_string().contains("already present") => {
        cleanup_stale_socket(&launch.control_path)?;
        provider.run(launch).await
    }
    r => r,
}

Prevention

Ensure shutdown handlers unbind the control socket
Use a supervisor/single-instance lock so two instances never race
On startup, detect and clean sockets left by crashed runs

When it happens

Trigger: validate_launch called while a previous FSKit service instance still holds the endpoint at resource_path/process-control.sock, or a crashed run left the socket file behind without cleanup.

Common situations: Starting a second instance of the same service; a previous run crashed without unlinking the socket; container restart reusing a volume with the old socket file.

Related errors

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

Appendix: source

Thrown at crates/astrid-storage-provider-fskit/src/service.rs:203

            .components()
            .any(|component| matches!(component, std::path::Component::ParentDir))
    {
        bail!("FSKit service control path is malformed");
    }
    let parent = control_path
        .parent()
        .context("FSKit service control path has no parent")?;
    platform_fs::validate_private_directory(parent)
        .context("validate private FSKit control parent")?;
    platform_fs::verify_no_redirects(control_path)
        .context("reject redirected FSKit control path")?;
    if control_path != resource_path.join("process-control.sock") {
        bail!("FSKit service control path is not the kernel endpoint");
    }
    if local_transport::endpoint_is_present(control_path)
        .context("inspect FSKit service control endpoint")?
    {
        bail!("FSKit service control endpoint is already present");
    }
    Ok(())
}

fn bind_control(path: &Path) -> Result<LocalListener> {
    local_transport::bind(path)
        .with_context(|| format!("bind FSKit service control {}", path.display()))
}

async fn probe_callback(launch: &StorageProviderServiceLaunchV1) -> Result<()> {
    let mut stream = local_transport::connect(&launch.lease.callback_path)
        .await
        .context("connect FSKit lease callback")?;
    let request = StorageFilesystemRequestV2 {
        protocol_version: STORAGE_FILESYSTEM_PROTOCOL_V2,
        request_id: format!("fskit-service-{}", launch.lease.mount_id),
        lease_token: launch.lease.lease_token.clone(),
        operation: StorageFilesystemOperationV2::Stat {

View on GitHub (pinned to affd8760f4)