denoland/deno · error · std::io::Error

node shim is not supported on this platform

Error message

node shim is not supported on this platform

What it means

The node-compat shim (the fake `node` executable Deno can install so child processes spawning `node` get routed back into the current Deno binary) is implemented with Unix hardlink/rename semantics and a Windows branch. This stub is compiled only for targets that are neither Unix nor Windows, and it unconditionally returns ErrorKind::Unsupported — the capability does not exist on such platforms.

Source

Thrown at cli/node_compat_shim.rs:284

  // binary's bytes with no extra disk; fall back to a copy across volumes.
  if shim_path.exists() {
    let _ = std::fs::remove_file(shim_path);
  }
  match std::fs::hard_link(current_exe, shim_path) {
    Ok(()) => Ok(()),
    Err(_) => {
      // Copy via a unique temp file then atomically rename into place.
      let tmp_path =
        shim_path.with_extension(format!("exe.tmp-{}", std::process::id()));
      std::fs::copy(current_exe, &tmp_path)?;
      std::fs::rename(&tmp_path, shim_path)
    }
  }
}

#[cfg(not(any(unix, windows)))]
fn create_shim(_shim_path: &Path, _current_exe: &Path) -> std::io::Result<()> {
  Err(std::io::Error::new(
    std::io::ErrorKind::Unsupported,
    "node shim is not supported on this platform",
  ))
}

/// Prepend `dir` to the process's own `PATH` (idempotently), so spawned
/// children inherit it.
fn prepend_self_path(dir: &Path) {
  let sep = if cfg!(windows) { ';' } else { ':' };
  let current = std::env::var_os("PATH").unwrap_or_default();
  // Idempotency: don't grow PATH if the dir is already present.
  let already_present = std::env::split_paths(&current).any(|p| p == dir);
  if already_present {
    return;
  }

  let mut new_path = OsString::from(dir);
  if !current.is_empty() {

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Run on a supported platform (Linux, macOS, Windows) where the shim is implemented
2. If you maintain a port, implement create_shim for your platform (copy + rename strategy) behind the appropriate cfg
3. Avoid the node-shim feature on unsupported targets (don't enable the code path that installs it)

// Rust: check platform support before touching the shim
fn node_shim_supported() -> bool {
    cfg!(any(unix, windows))
}
if !node_shim_supported() { /* skip node-shim install, use explicit `deno` path */ }

match create_node_shim(&shim_path, &current_exe) {
    Err(e) if e.kind() == std::io::ErrorKind::Unsupported => {
        // platform cannot host a node shim: fall back to spawning `deno` directly
        spawn_deno_directly();
    }
    r => r?,
}

When it happens

Trigger: Building/running the Deno CLI for an exotic target (e.g. wasm32, fuchsia, redox) and triggering node-shim installation (the code path that would create the shim). On Linux/macOS/Windows builds the real implementations are compiled instead, so this error cannot occur there.

Common situations: Community ports of Deno to niche OSes; cross-compilation experiments; static analysis/tooling that enumerates all cfg branches. Not reachable in official x64/arm64 Linux, macOS, or Windows builds.

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

• Expected 'fn' field in the first argument to be a bench func
• The benchmark which this context belongs to is not being exe
• Empty filepath.
• resolve hook must return { shortCircuit: true } or call next
• load hook must return { shortCircuit: true } or call nextLoa

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/00b521c6c3ac27c2. Report an issue: GitHub.