GitoxideLabs/gitoxide · error

symbolic links are not supported on this platform

Error message

symbolic links are not supported on this platform

What it means

gix-fs' `symlink::create` is only compiled for unix, windows, and wasi targets. On any other platform the stub returns `io::ErrorKind::Unsupported` because the OS/runtime provides no symlink creation mechanism, so the library can only report the operation as unsupported.

Solutions

1. Target a supported platform (unix, windows, wasi).
2. Feature-detect at runtime and skip or substitute copy-based behavior when `create` returns `ErrorKind::Unsupported`.
3. Gate the calling code path behind a cfg/check so symlink creation is never attempted on unsupported targets.

Example fix

// before: unconditionally creating a symlink
let _ = gix_fs::symlink::create(&original, &link);

// after: fall back when unsupported
if let Err(e) = gix_fs::symlink::create(&original, &link) {
    if e.kind() == std::io::ErrorKind::Unsupported {
        std::fs::copy(&original, &link)?; // or skip
    } else { return Err(e.into()); }
}

// compile-time guard
#[cfg(not(any(unix, windows, target_os = "wasi")))]
compile_error!("this build target cannot create symlinks");

if let Err(e) = gix_fs::symlink::create(&original, &link) {
    if e.kind() == std::io::ErrorKind::Unsupported { /* fallback: copy or skip */ }
    else { return Err(e.into()); }
}

When it happens

Trigger: Calling `gix_fs::symlink::create(original, link)` on a platform excluded by `#[cfg(not(any(unix, windows, target_os = "wasi")))]`.

Common situations: Building/running for an exotic target (embedded, wasm without wasi, other OSes) where git worktrees or executable-bit emulation attempt to create symlinks.

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

• we are not on 16 bit systems
• no symlink related errors
• ' ' is not a valid configuration key
• Cannot use iter_v1() on index of type
• Cannot use iter_v2() on index of type

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/fa27c6da64de7592. Report an issue: GitHub.

Appendix: source

Thrown at gix-fs/src/symlink.rs:24

#[cfg(unix)]
pub fn create(original: &Path, link: &Path) -> io::Result<()> {
    std::os::unix::fs::symlink(original, link)
}

/// Create a new symlink at `link` which points to `original`.
///
/// Note that `original` doesn't have to exist.
#[cfg(target_os = "wasi")]
pub fn create(original: &Path, link: &Path) -> io::Result<()> {
    std::fs::soft_link(original, link)
}

/// Create a new symlink at `link` which points to `original`.
///
/// Note that symbolic links are unsupported on this platform.
#[cfg(not(any(unix, windows, target_os = "wasi")))]
pub fn create(_original: &Path, _link: &Path) -> io::Result<()> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "symbolic links are not supported on this platform",
    ))
}

/// Remove a symlink.
///
/// Note that on only on windows this is special.
#[cfg(any(unix, target_os = "wasi"))]
pub fn remove(path: &Path) -> io::Result<()> {
    std::fs::remove_file(path)
}

/// Remove a symlink.
#[cfg(not(any(unix, windows, target_os = "wasi")))]
pub fn remove(_path: &Path) -> io::Result<()> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,

View on GitHub (pinned to e73179060b)