ducaale/xh · error

--unix-socket is not supported on this platform

Error message

--unix-socket is not supported on this platform

What it means

The `--unix-socket` option directs the HTTP client to connect over a Unix domain socket instead of TCP, but this is only implemented on Unix-like platforms. On non-Unix builds (e.g. Windows), `run` checks `args.unix_socket.is_some()` under `#[cfg(not(unix))]` and returns this error instead of silently ignoring the flag.

Solutions

1. Run the command on a Unix-like platform (Linux/macOS) where Unix domain sockets are supported.
2. On Windows, use the daemon's TCP endpoint instead of its unix socket and drop the `--unix-socket` flag.
3. Use WSL on Windows to get a Unix environment for the socket-based call.

Example fix

// before (Windows cmd)
xh --unix-socket /var/run/docker.sock GET http://localhost/v1.41/version
// after
xh GET http://localhost:2375/v1.41/version

# guard in shell scripts:
if [[ "$OSTYPE" != linux* && "$OSTYPE" != darwin* ]] && [[ "$*" == *--unix-socket* ]]; then
  echo "--unix-socket unsupported on this platform"; exit 1
fi

// Rust caller:
match run(args) {
    Err(e) if e.to_string().contains("unix-socket") => fallback_to_tcp(),
    other => other,
}

When it happens

Trigger: Invoking `xh --unix-socket /path/to.sock ...` on a platform not compiled as `unix` (typically Windows), or using a Windows-subsystem build where Unix sockets are unavailable.

Common situations: Porting shell scripts that talk to Docker's unix socket or local daemons from Linux to Windows; CI matrix runs where the same command is executed on Windows runners.

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

• message-signature: RSA private keys require an explicit…
• Unsupported option
• Unknown option
• is not a valid value
• Connection timeout is negative

AI-assisted analysis of ducaale/xh@2404aceecc (2026-09-13). Data as JSON: /api/errors/a56cade6834909d1. Report an issue: GitHub.

Appendix: source

Thrown at src/main.rs:383

                            }
                            None
                        })
                        .with_context(|| format!("Couldn't bind to {:?}", name_or_ip))?;
                    log::debug!("Resolved {name_or_ip:?} to {ip_addr:?}");
                    client = client.local_address(ip_addr);
                }
            }
        };
    }

    #[cfg(unix)]
    if let Some(socket_path) = args.unix_socket {
        client = client.unix_socket(socket_path);
    }

    #[cfg(not(unix))]
    if args.unix_socket.is_some() {
        return Err(anyhow::anyhow!(
            "--unix-socket is not supported on this platform"
        ));
    }

    for resolve in args.resolve {
        client = client.resolve(&resolve.domain, SocketAddr::new(resolve.addr, 0));
    }

    log::trace!("Finalizing reqwest client");
    log::trace!("{client:#?}");
    let client = client.build()?;

    let mut session = match &args.session {
        Some(name_or_path) => Some(
            Session::load_session(url.clone(), name_or_path.clone(), args.is_session_read_only)
                .with_context(|| {
                    format!("couldn't load session {:?}", name_or_path.to_string_lossy())
                })?,

View on GitHub (pinned to 2404aceecc)