openai/codex · error · anyhow::Error

codex app-server daemon lifecycle is only supported on Unix

Error message

codex app-server daemon lifecycle is only supported on Unix platforms

What it means

This is the umbrella platform gate: every public entry point of codex_app_server_daemon (run, bootstrap, ensure_remote_control_ready, enable_remote_control_on_socket, start_remote_control_pairing, set_remote_control, run_pid_update_loop) calls ensure_supported_platform() first, and on non-Unix targets it returns exactly this error. The Unix-only backend stubs ([40]-[43]) sit behind it, so normally you see this message instead of theirs because it fires first.

Source

Thrown at codex-rs/app-server-daemon/src/lib.rs:248

    ensure_supported_platform()?;
    Daemon::from_environment()?.set_remote_control(mode).await
}

pub async fn run_pid_update_loop(
    http_client_factory: codex_http_client::HttpClientFactory,
) -> Result<()> {
    ensure_supported_platform()?;
    update_loop::run(http_client_factory).await
}

#[cfg(unix)]
fn ensure_supported_platform() -> Result<()> {
    Ok(())
}

#[cfg(not(unix))]
fn ensure_supported_platform() -> Result<()> {
    Err(anyhow!(
        "codex app-server daemon lifecycle is only supported on Unix platforms"
    ))
}

struct Daemon {
    socket_path: PathBuf,
    pid_file: PathBuf,
    update_pid_file: PathBuf,
    operation_lock_file: PathBuf,
    settings_file: PathBuf,
    managed_codex_bin: PathBuf,
}

impl Daemon {
    fn from_environment() -> Result<Self> {
        let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
        let socket_path = app_server_control_socket_path(codex_home.as_path())?
            .as_path()

View on GitHub (pinned to 339751715c)

Solutions

1. Run the daemon lifecycle on macOS/Linux/WSL — the whole lifecycle (signals, flock, Unix sockets, setsid) is Unix-only.
2. Gate call sites or CLI subcommands with #[cfg(unix)] so Windows builds never dispatch into the daemon.
3. Fail early with your own message when cfg!(unix) is false instead of propagating this one from deep in the call.
4. In shared code, return a no-op or 'unsupported here' result on non-Unix platforms.

Example fix

// before: dispatched on every platform
codex_app_server_daemon::run(cmd).await?;

// after: compile-time gate in the CLI
#[cfg(unix)]
codex_app_server_daemon::run(cmd).await?;
#[cfg(not(unix))]
anyhow::bail!("app-server daemon is unavailable on this platform");

// before any daemon API
if !cfg!(unix) {
    return Err(anyhow::anyhow!("daemon lifecycle unsupported on this platform"));
}

Don't catch — branch on cfg!(unix) at the call site and skip daemon functionality on non-Unix targets; the error carries no recoverable state.

When it happens

Trigger: Calling any of the crate's public lifecycle APIs on a non-Unix target — e.g. a Windows build of a CLI dispatching 'codex app-server daemon start' or the pid update loop. On Unix the twin at lib.rs:242 returns Ok(()) and never errors.

Common situations: Windows dev machines or CI runners exercising daemon subcommands; cross-compiled binaries shipped to non-Unix hosts; feature-gating mistakes that compile daemon code into a Windows build.

Related errors

• pid-managed app-server shutdown is unsupported on this platf
• pid-managed updater shutdown is unsupported on this platform
• failed to read start time for pid-managed app server {pid}
• pid-managed app server {pid} has no recorded start time
• app-server closed the control socket

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/0aba75801af89ce3. Report an issue: GitHub.