{"record":{"id":"f05a27ee68f15600","repo":"seanmonstar/warp","slug":"failed-to-bind-to-address","errorCode":null,"errorMessage":"failed to bind to address","messagePattern":"failed to bind to address","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/server.rs","lineNumber":78,"sourceCode":"    /// Panics if we are unable to bind to the provided address.\n    ///\n    /// To handle bind failures, bind a listener and call `incoming()`.\n    pub async fn run(self, addr: impl Into<SocketAddr>) {\n        self.bind(addr).await.run().await;\n    }\n\n    /// Binds this server.\n    ///\n    /// # Panics\n    ///\n    /// Panics if we are unable to bind to the provided address.\n    ///\n    /// To handle bind failures, bind a listener and call `incoming()`.\n    pub async fn bind(self, addr: impl Into<SocketAddr>) -> Server<F, tokio::net::TcpListener, R> {\n        let addr = addr.into();\n        let acceptor = tokio::net::TcpListener::bind(addr)\n            .await\n            .expect(\"failed to bind to address\");\n\n        self.incoming(acceptor)\n    }\n\n    /// Configure the server with an acceptor of incoming connections.\n    pub fn incoming<A>(self, acceptor: A) -> Server<F, A, R> {\n        Server {\n            acceptor,\n            filter: self.filter,\n            pipeline: self.pipeline,\n            runner: self.runner,\n        }\n    }\n\n    // pub fn conn\n}\n\nimpl<F, A, R> Server<F, A, R>","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/seanmonstar/warp/blob/ff34d7213ed55ec342304aa7ff6ac4b351da9e66/src/server.rs#L60-L96","documentation":"`warp::Server::bind(addr)` awaits `tokio::net::TcpListener::bind(addr)` and `.expect(\"failed to bind to address\")`s the result (src/server.rs:78). If the OS refuses to bind (port already in use, permission denied, invalid address), the server panics at startup instead of returning an error. The docs explicitly recommend using `bind` on a listener + `incoming()` when you need to handle bind failures gracefully.","triggerScenarios":"Starting the server with `warp::serve(routes).run(([127,0,0,1],3030))`/`bind((addr, port))` when the port is already taken by another process, the port is privileged (<1024) without root, or the interface address doesn't exist on the host.","commonSituations":"Two dev servers running concurrently; a previous instance that didn't release the port (crashed process, lingering container); deploying to a platform where PORT is privileged or already bound; typo'd or broadcast/unassigned listen addresses in config.","solutions":["Bind the listener yourself and use `incoming()` so errors are values: `TcpListener::bind(addr).await?` then `warp::serve(routes).incoming(listener)`","Check what occupies the port (`lsof -i :3030` / `ss -ltnp`) and stop it or pick a free port","On Linux enable SO_REUSEADDR semantics via your own listener setup (socket2 crate) if TIME_WAIT reuse is the issue","Use an unprivileged port (>=1024) or run with proper capabilities when binding low ports"],"exampleFix":"// before\nwarp::serve(routes).run(([127, 0, 0, 1], 3030)).await;\n// after\nlet listener = tokio::net::TcpListener::bind(([127, 0, 0, 1], 3030))\n    .await\n    .map_err(|e| eprintln!(\"failed to bind: {e}\"))?;\nwarp::serve(routes).incoming(listener).await;","handlingStrategy":"try-catch","validationCode":"// before starting the server, check the port is free:\nasync fn port_free(addr: std::net::SocketAddr) -> bool {\n    tokio::net::TcpListener::bind(addr).await.is_ok()\n}","typeGuard":null,"tryCatchPattern":"let listener = tokio::net::TcpListener::bind(addr)\n    .await\n    .map_err(|e| { eprintln!(\"bind {addr} failed: {e}\"); e })?;\nwarp::serve(routes).incoming(listener).await;","preventionTips":["Prefer binding your own TcpListener + incoming() over run()/bind() so bind errors are recoverable","Read the listen port from an env var (e.g. PORT) with a free fallback instead of hardcoding","In dev, use a process manager or port-picking (bind port 0 and report the chosen port)","Check for leftover processes/containers holding the port before restart scripts"],"tags":["network","panic","bind","tcp","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"ff34d7213ed55ec342304aa7ff6ac4b351da9e66","analyzedAt":"2026-09-09T16:57:46.316Z","contentChangedAt":"2026-09-09T16:57:46.316Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}