What causes "symlinks are only supported on unix-like systems" in nikivdev/code?

Run the tool on Linux/macOS (or inside WSL using the Linux binary)

symlinks are only supported on unix-like systems

Error message

symlinks are only supported on unix-like systems

What it means

create_symlink is the cross-platform symlink helper; symlink creation is only implemented for unix-like targets. On non-unix builds (cfg(not(unix)), e.g. Windows), the function deliberately fails with this message instead of attempting an unsupported operation. Called from ensure_link_targets when setting up dotfile links.

Source

Thrown at src/home.rs:474

    Ok(())
}

fn create_symlink(source: &Path, dest: &Path) -> Result<()> {
    #[cfg(unix)]
    {
        std::os::unix::fs::symlink(source, dest).with_context(|| {
            format!(
                "failed to symlink {} -> {}",
                dest.display(),
                source.display()
            )
        })?;
        return Ok(());
    }
    #[cfg(not(unix))]
    {
        bail!("symlinks are only supported on unix-like systems");
    }
}

fn ensure_kar_repo(flow_bin: &Path, prefer_ssh: bool, repo_url: &str) -> Result<()> {
    let repo_url = coerce_repo_url(repo_url, prefer_ssh);
    let repo = parse_repo_input(&repo_url)?;
    let root = config::expand_path(DEFAULT_REPOS_ROOT);
    let owner_dir = root.join(&repo.owner);
    let repo_path = owner_dir.join(&repo.repo);

    ensure_repo(&repo_path, Some(&repo.clone_url), "kar", true)?;

    let flow_toml = repo_path.join("flow.toml");
    if !flow_toml.exists() {
        println!(
            "No flow.toml found in {}; skipping f deploy",
            repo_path.display()
        );

View on GitHub (pinned to a747e741ae)

Solutions

Run the tool on Linux/macOS (or inside WSL using the Linux binary)
Skip the symlink-sync feature on Windows and manage links manually
Use Windows Developer Mode + a fork adding junction/symlink support

Defensive patterns

Strategy: fallback

Validate before calling

#[cfg(not(unix))]
if uses_symlink_sync {
    eprintln!("symlink sync unsupported on this platform; skipping");
}

Type guard

fn symlinks_supported() -> bool { cfg!(unix) }

Try / catch

match create_symlink(...) {
    Ok(()) => {},
    Err(e) if e.to_string().contains("only supported on unix") => {
        fallback_copy(&src, &dest)?; // copy instead of link on unsupported platforms
    }
    Err(e) => return Err(e),
}

Prevention

Run dotfile sync on Linux/macOS or inside WSL with the Linux binary
Gate sync features behind cfg(unix) in cross-platform scripts
Document platform limits in CI matrices (skip Windows sync jobs)

When it happens

Trigger: Running a binary compiled for a non-unix platform and reaching ensure_link_targets -> create_symlink; e.g. using the dotfile sync feature on Windows (including Windows without a unix compatibility layer).

Common situations: Running the tool on Windows; using WSL incorrectly by invoking the Windows binary instead of the Linux one; CI runners on Windows executing the sync step.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/ac913d8cc7bc2bbb. Report an issue: GitHub.