What causes "failed to wait for agent server exit: {err}" in zed-industries/zed?

Read the agent server stderr captured in the debug log that accompanies this error to find the underlying spawn failure

failed to wait for agent server exit: {err}

Error message

failed to wait for agent server exit: {err}

What it means

While spawning an ACP agent server, Zed races the stdio connection handshake against the child process's exit status. If waiting on the child (child.status()) itself returns an OS-level error — rather than a normal exit status, which is reported separately with captured stderr — the spawn fails with this message.

Source

Thrown at crates/agent_servers/src/acp.rs:963

            .spawn_dedicated(move |_executor| async move {
                if let Err(err) = connection_future.await {
                    log::error!("ACP connection error: {err}");
                }
            });

        let connection_rx = async move {
            connection_rx
                .await
                .context("Failed to receive ACP connection handle")
        }
        .boxed_local();
        let status_fut = child
            .status()
            .map({
                let debug_log = debug_log.clone();
                move |status| match status {
                    Ok(status) => Ok(exited_load_error_with_stderr(status, &debug_log)),
                    Err(err) => Err(anyhow!("failed to wait for agent server exit: {err}")),
                }
            })
            .boxed_local();
        let (connection, status_fut) = match futures::future::select(connection_rx, status_fut)
            .await
        {
            futures::future::Either::Left((connection, status_fut)) => (connection?, status_fut),
            futures::future::Either::Right((load_error, _connection_rx)) => {
                return Err(load_error?.into());
            }
        };

        // Set up the foreground dispatch loop to process work items from handlers.
        let dispatch_context = ClientContext {
            sessions: sessions.clone(),
            session_list: client_session_list.clone(),
            request_elicitations: request_elicitations.clone(),
        };

View on GitHub (pinned to bc538def45)

Solutions

Read the agent server stderr captured in the debug log that accompanies this error to find the underlying spawn failure
Run the configured agent command manually in a terminal to confirm it starts and speaks ACP over stdio
Update Zed and the agent package to pick up process-handling fixes

Defensive patterns

Strategy: try-catch

Try / catch

match connect_agent_server(config).await {
    Err(err) if err.to_string().contains("failed to wait for agent server exit") => {
        // surface the captured stderr/debug log, then re-spawn once;
        // a second failure indicates a broken command, not a transient OS issue
    }
    result => result,
}

Prevention

Verify the agent command runs and stays alive in a terminal before configuring it
Avoid wrapper scripts that double-fork or detach — the parent must stay alive to be waited on
Always read the captured stderr debug log before debugging the connection code

When it happens

Trigger: The wait on the spawned agent process fails outright: the process handle was invalidated (e.g. a wrapper script that double-forks or detaches), the child was reaped elsewhere, or OS resource limits interfere with waiting.

Common situations: Agent server crashes at startup (missing binary, missing runtime) or is launched through a shell wrapper that detaches; sandboxed or containerized environments with unusual process semantics.

Related errors

AI-assisted analysis of zed-industries/zed@bc538def45 (2026-08-16). Data as JSON: /api/errors/128a57908ddcd605. Report an issue: GitHub.