{"record":{"id":"fa27c6da64de7592","repo":"GitoxideLabs/gitoxide","slug":"symbolic-links-are-not-supported-on-this-platform","errorCode":null,"errorMessage":"symbolic links are not supported on this platform","messagePattern":"symbolic links are not supported on this platform","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gix-fs/src/symlink.rs","lineNumber":24,"sourceCode":"#[cfg(unix)]\npub fn create(original: &Path, link: &Path) -> io::Result<()> {\n    std::os::unix::fs::symlink(original, link)\n}\n\n/// Create a new symlink at `link` which points to `original`.\n///\n/// Note that `original` doesn't have to exist.\n#[cfg(target_os = \"wasi\")]\npub fn create(original: &Path, link: &Path) -> io::Result<()> {\n    std::fs::soft_link(original, link)\n}\n\n/// Create a new symlink at `link` which points to `original`.\n///\n/// Note that symbolic links are unsupported on this platform.\n#[cfg(not(any(unix, windows, target_os = \"wasi\")))]\npub fn create(_original: &Path, _link: &Path) -> io::Result<()> {\n    Err(io::Error::new(\n        io::ErrorKind::Unsupported,\n        \"symbolic links are not supported on this platform\",\n    ))\n}\n\n/// Remove a symlink.\n///\n/// Note that on only on windows this is special.\n#[cfg(any(unix, target_os = \"wasi\"))]\npub fn remove(path: &Path) -> io::Result<()> {\n    std::fs::remove_file(path)\n}\n\n/// Remove a symlink.\n#[cfg(not(any(unix, windows, target_os = \"wasi\")))]\npub fn remove(_path: &Path) -> io::Result<()> {\n    Err(io::Error::new(\n        io::ErrorKind::Unsupported,","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/GitoxideLabs/gitoxide/blob/e73179060badf27222d790981fac3f84c1830a7e/gix-fs/src/symlink.rs#L6-L42","documentation":"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.","triggerScenarios":"Calling `gix_fs::symlink::create(original, link)` on a platform excluded by `#[cfg(not(any(unix, windows, target_os = \"wasi\")))]`.","commonSituations":"Building/running for an exotic target (embedded, wasm without wasi, other OSes) where git worktrees or executable-bit emulation attempt to create symlinks.","solutions":["Target a supported platform (unix, windows, wasi).","Feature-detect at runtime and skip or substitute copy-based behavior when `create` returns `ErrorKind::Unsupported`.","Gate the calling code path behind a cfg/check so symlink creation is never attempted on unsupported targets."],"exampleFix":"// before: unconditionally creating a symlink\nlet _ = gix_fs::symlink::create(&original, &link);\n\n// after: fall back when unsupported\nif let Err(e) = gix_fs::symlink::create(&original, &link) {\n    if e.kind() == std::io::ErrorKind::Unsupported {\n        std::fs::copy(&original, &link)?; // or skip\n    } else { return Err(e.into()); }\n}","handlingStrategy":"fallback","validationCode":"// compile-time guard\n#[cfg(not(any(unix, windows, target_os = \"wasi\")))]\ncompile_error!(\"this build target cannot create symlinks\");","typeGuard":null,"tryCatchPattern":"if let Err(e) = gix_fs::symlink::create(&original, &link) {\n    if e.kind() == std::io::ErrorKind::Unsupported { /* fallback: copy or skip */ }\n    else { return Err(e.into()); }\n}","preventionTips":["Feature-detect symlink support before running worktree-dependent logic.","Design flows so symlinks are optional (copy fallback).","Avoid targeting non-unix/windows/wasi platforms for repo-mutating tooling."],"tags":["symlink","platform","unsupported","rust"],"backgroundTag":"unsupported-platform","analyzedSha":"e73179060badf27222d790981fac3f84c1830a7e","analyzedAt":"2026-09-08T11:26:50.865Z","contentChangedAt":"2026-09-08T11:26:50.865Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}