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

automatic migration of unreleased Windows layout-one homes…

Error message

automatic migration of unreleased Windows layout-one homes is unsupported; use the explicit developer importer

What it means

On Windows builds, reject_automatic_windows_layout_one unconditionally rejects the v1→v2 migration for layout-one homes: Windows layout-one homes were never released, so the library refuses to migrate them automatically and returns io::ErrorKind::Unsupported, directing developers to the explicit developer importer. This gate runs inside both begin_layout_v2_migration and complete_layout_v2.

Solutions

  1. Use the explicit developer importer tool as the error message directs, instead of the automatic migration path
  2. If the Windows home is disposable test data, delete it (or its sentinel) and let Astrid create a fresh v2 home
  3. Run the migration on a non-Windows host if the home genuinely originated there, then move the migrated home
  4. Confirm you actually intend to migrate a layout-one home — current-version (v2) homes skip this gate entirely

Example fix

// before: automatic migration on Windows
home.begin_layout_v2_migration(&target)?; // Unsupported
// after: use the developer importer
// astrid-dev import-layout-one --home ~/.astrid
// or, for throwaway data:
std::fs::remove_dir_all("~/.astrid")?; // recreate fresh v2 home
Defensive patterns

Strategy: fallback

Validate before calling

#[cfg(windows)]
fn needs_developer_importer(home: &AstridHome) -> bool {
    home.layout_version().ok().flatten().as_deref() == Some(astrid_core::LEGACY_LAYOUT_VERSION)
}

Type guard

fn automatic_migration_available() -> bool {
    !cfg!(windows)
}

Try / catch

match home.begin_layout_v2_migration(&target) {
    Err(e) if e.kind() == std::io::ErrorKind::Unsupported
        && e.to_string().contains("Windows layout-one") => {
        // invoke the developer importer or recreate the home
    },
    r => r?,
}

Prevention

When it happens

Trigger: Calling begin_layout_v2_migration or complete_layout_v2 on a Windows build against a home whose sentinel is the legacy layout-one version. Any legacy-version home on Windows triggers this immediately, before any path or content checks.

Common situations: Running a Windows development build against an old test home from an unreleased Windows layout; CI or a developer machine on Windows hitting the legacy sentinel left in a test fixture.

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

Appendix: source

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

                    )
                })?;
            },
            Err(error) => return Err(error),
        }
    }
}

fn path_entry_present(path: &Path) -> io::Result<bool> {
    match std::fs::symlink_metadata(path) {
        Ok(_) => Ok(true),
        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false),
        Err(error) => Err(error),
    }
}

#[cfg(windows)]
fn reject_automatic_windows_layout_one() -> io::Result<()> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "automatic migration of unreleased Windows layout-one homes is unsupported; use the explicit developer importer",
    ))
}

#[cfg(not(windows))]
#[expect(
    clippy::unnecessary_wraps,
    reason = "the cross-platform migration gate has one fallible signature"
)]
fn reject_automatic_windows_layout_one() -> io::Result<()> {
    Ok(())
}

#[cfg(not(target_family = "wasm"))]
fn ensure_migration_capacity(target: &Path, source_bytes: u64) -> io::Result<()> {
    let available = fs2::available_space(target)?;
    ensure_available_migration_capacity(available, source_bytes)

View on GitHub (pinned to affd8760f4)