zed-industries/zed · error

failed to bind TCP listener

Error message

failed to bind TCP listener

What it means

Fires in collab's main when binding the axum Router's TCP listener fails, typically because the configured port is already in use or the address is not bindable (permissions, IPv6 unavailability). The collab service cannot serve requests without the listener.

Source

Thrown at crates/collab/src/main.rs:66

                Some("collab") => ServiceMode::Collab,
                Some("api") => ServiceMode::Api,
                Some("all") => ServiceMode::All,
                _ => {
                    return Err(anyhow!("usage: collab <version | serve <api|collab|all>>"))?;
                }
            };

            let config = envy::from_env::<Config>().expect("error loading config");
            init_tracing(&config);
            init_panic_hook();

            let mut app = Router::new()
                .route("/", get(handle_root))
                .route("/healthz", get(handle_liveness_probe))
                .layer(Extension(mode));

            let listener = TcpListener::bind(format!("0.0.0.0:{}", config.http_port))
                .expect("failed to bind TCP listener");

            let mut on_shutdown = None;

            if mode.is_collab() || mode.is_api() {
                setup_app_database(&config).await?;

                let state = AppState::new(config, Executor::Production).await?;

                if mode.is_collab() {
                    let epoch = state
                        .db
                        .create_server(&state.config.zed_environment)
                        .await?;
                    let rpc_server = collab::rpc::Server::new(epoch, state.clone());
                    rpc_server.start().await?;

                    app = app.merge(collab::rpc::routes(rpc_server.clone()));

View on GitHub (pinned to 9d272b0363)

Solutions

1. Check for another process already bound to the configured port (lsof/ss)
2. Change the port via configuration or stop the conflicting service
3. Verify the listen address is valid and permitted (e.g. CAP_NET_BIND_SERVICE for ports < 1024)

When it happens

Trigger: Thrown at crates/collab/src/main.rs:66 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zed-industries/zed@9d272b0363 (2026-08-20). Data as JSON: /api/errors/5270a6c1ed5fa858. Report an issue: GitHub.