astrid-runtime/astrid · error · io::Error

stable private file identity is unavailable

Error message

stable private file identity is unavailable

What it means

opened_file_identity builds a FileIdentity from the OS file index; on targets that are neither Unix nor Windows there is no stable identity API, so it returns ErrorKind::Unsupported with this message. The capability requires comparing file identities, which the platform cannot provide.

Source

Thrown at crates/astrid-storage/src/engine/durable/representations/contiguous/namespace.rs:193

    use windows_sys::Win32::Storage::FileSystem::{
        BY_HANDLE_FILE_INFORMATION, GetFileInformationByHandle,
    };

    let mut info = BY_HANDLE_FILE_INFORMATION::default();
    // SAFETY: `file` owns a live Windows handle and `info` is writable.
    #[allow(unsafe_code)]
    if unsafe { GetFileInformationByHandle(file.as_raw_handle().cast(), &raw mut info) } == 0 {
        return Err(io::Error::last_os_error());
    }
    Ok(FileIdentity {
        volume: VolumeId(u64::from(info.dwVolumeSerialNumber)),
        file: FileId((u64::from(info.nFileIndexHigh) << 32) | u64::from(info.nFileIndexLow)),
    })
}

#[cfg(not(any(unix, windows)))]
fn opened_file_identity(_file: &File) -> io::Result<FileIdentity> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "stable private file identity is unavailable",
    ))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn directory_sync_portability_contract_accepts_a_directory_capability() {
        let temporary = tempfile::tempdir().unwrap();
        let directory =
            Dir::open_ambient_dir(temporary.path(), cap_std::ambient_authority()).unwrap();

        sync_directory(&directory).unwrap();
    }
}

View on GitHub (pinned to affd8760f4)

Solutions

  1. Run on a supported platform (Unix or Windows target triple)
  2. Implement opened_file_identity for your target OS and gate it with the appropriate cfg
  3. Fall back to a storage engine that does not require identity checks on this platform
  4. Skip identity verification only if you fully control the threat model — not recommended

Example fix

// before
#[cfg(not(any(unix, windows)))]
fn opened_file_identity(_file: &File) -> io::Result<FileIdentity> { Err(...) }
// after
#[cfg(target_family = "wasm")]
fn opened_file_identity(_file: &File) -> io::Result<FileIdentity> {
    Ok(FileIdentity { device: 0, index: wasm_fd_index(_file) })
}
Defensive patterns

Strategy: fallback

Validate before calling

if !cfg!(any(unix, windows)) {
    // select backend that does not require file-identity checks
    use_memory_backend();
}

Type guard

const OPENED_IDENTITY_SUPPORTED: bool = cfg!(any(unix, windows));

Try / catch

match open_file_result {
    Err(e) if e.kind() == io::ErrorKind::Unsupported => use_non_identity_backend(),
    r => r,
}

Prevention

When it happens

Trigger: Any representation open path that compares opened file identities (open_file / open_component flow) compiled for a non-unix/non-windows target such as wasm32-unknown-unknown or a custom RTOS.

Common situations: Running the durable representation engine in wasm/browser or embedded sandboxes; cross-compilation for exotic targets during testing.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

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