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

layout migration capacity probing is unavailable in a WebAss

Error message

layout migration capacity probing is unavailable in a WebAssembly guest

What it means

This io::Error with ErrorKind::Unsupported is thrown by the wasm-specific stub of ensure_migration_capacity in dirs_layout.rs. Before writing a new layout record the library probes whether the target filesystem/volume has enough capacity for the migrated layout; that capacity probing requires OS filesystem APIs that do not exist inside a WebAssembly guest. The function therefore unconditionally fails when layout migration would need to run under wasm.

Source

Thrown at crates/astrid-core/src/dirs_layout.rs:501

fn ensure_available_migration_capacity(available: u64, source_bytes: u64) -> io::Result<()> {
    let required = source_bytes
        .checked_mul(2)
        .and_then(|bytes| bytes.checked_add(LAYOUT_MIGRATION_HEADROOM_BYTES))
        .ok_or_else(|| io::Error::other("layout migration capacity requirement overflow"))?;
    if available < required {
        return Err(io::Error::new(
            io::ErrorKind::StorageFull,
            format!(
                "insufficient free space for layout migration: need {required} bytes, have {available} bytes"
            ),
        ));
    }
    Ok(())
}

#[cfg(target_family = "wasm")]
fn ensure_migration_capacity(_target: &Path, _source_bytes: u64) -> io::Result<()> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "layout migration capacity probing is unavailable in a WebAssembly guest",
    ))
}

fn atomic_write(path: &Path, bytes: &[u8]) -> io::Result<()> {
    #[cfg(windows)]
    {
        crate::platform_fs::atomic_write_private_file(path, bytes)
    }

    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt as _;

        let parent = path.parent().ok_or_else(|| {
            io::Error::new(io::ErrorKind::InvalidInput, "layout record has no parent")
        })?;

View on GitHub (pinned to affd8760f4)

Solutions

Do not run layout migrations inside wasm; perform them on a native (unix/windows) host before shipping data to the wasm environment.
Gate the migration call behind a target-family check in your own code (#[cfg(not(target_family = "wasm"))]) and skip or defer it in wasm builds.
Pre-ensure capacity externally (mount a larger volume / free space) and use an API path that does not trigger capacity probing.
File/verify wasm support status for this operation in the crate docs; treat it as a hard unsupported operation.

Example fix

// before (wasm guest)
write_layout_version(&dir, &record)?;
// after
#[cfg(not(target_family = "wasm"))]
write_layout_version(&dir, &record)?;
#[cfg(target_family = "wasm")]
// defer migration to a native host step

Defensive patterns

Strategy: fallback

Validate before calling

#[cfg(target_family = "wasm")]
fn migration_supported() -> bool { false }
#[cfg(not(target_family = "wasm"))]
fn migration_supported() -> bool { true }

Type guard

fn supports_layout_migration() -> bool {
    !cfg!(target_family = "wasm")
}

Try / catch

match write_layout_version(&dir, &record) {
    Err(e) if e.kind() == io::ErrorKind::Unsupported => defer_migration_to_native_host(),
    other => other?,
}

Prevention

Check cfg!(target_family = "wasm") before invoking layout migration APIs
Run migrations on a native host before deploying data to wasm guests
Document platform support per operation in your build pipeline

When it happens

Trigger: Calling write_layout_version (directly or through a layout migration such as begin_layout_v2_migration) compiled to a wasm target, when the target size check path needs ensure_migration_capacity to verify source_bytes fit at _target.

Common situations: Running the crate in a browser/WASI sandbox (e.g. in a Cloudflare Worker, browser wasm module, or wasmtime) and attempting a layout v1->v2 migration; embedding astrid-core in a wasm build where directory-layout upgrades were assumed to work like on desktop targets.

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/95c64b62cefe6b0a. Report an issue: GitHub.