{"record":{"id":"9733fa7ab0933918","repo":"grpc/grpc-java","slug":"failed-to-bind-to-addresses-addresses","errorCode":null,"errorMessage":"Failed to bind to addresses ${addresses}","messagePattern":"Failed to bind to addresses (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"netty/src/main/java/io/grpc/netty/NettyServer.java","lineNumber":343,"sourceCode":"            new Callable<Map<ChannelFuture, SocketAddress>>() {\n          @Override\n          public Map<ChannelFuture, SocketAddress> call() {\n            Map<ChannelFuture, SocketAddress> bindFutures = new HashMap<>();\n            for (SocketAddress address: addresses) {\n                ChannelFuture future = b.bind(address);\n                channelGroup.add(future.channel());\n                bindFutures.put(future, address);\n            }\n            return bindFutures;\n          }\n        }\n    );\n    Map<ChannelFuture, SocketAddress> channelFutures =\n        bindCallFuture.awaitUninterruptibly().getNow();\n\n    if (!bindCallFuture.isSuccess()) {\n      channelGroup.close().awaitUninterruptibly();\n      throw new IOException(String.format(\"Failed to bind to addresses %s\",\n          addresses), bindCallFuture.cause());\n    }\n    final List<InternalInstrumented<SocketStats>> socketStats = new ArrayList<>();\n    for (Map.Entry<ChannelFuture, SocketAddress> entry: channelFutures.entrySet()) {\n      // We'd love to observe interruption, but if interrupted we will need to close the channel,\n      // which itself would need an await() to guarantee the port is not used when the method\n      // returns. See #6850\n      final ChannelFuture future = entry.getKey();\n      if (!future.awaitUninterruptibly().isSuccess()) {\n        channelGroup.close().awaitUninterruptibly();\n        throw new IOException(String.format(\"Failed to bind to address %s\",\n            entry.getValue()), future.cause());\n      }\n      final InternalInstrumented<SocketStats> listenSocketStats =\n          new ListenSocket(future.channel());\n      channelz.addListenSocket(listenSocketStats);\n      socketStats.add(listenSocketStats);\n      future.channel().closeFuture().addListener(new ChannelFutureListener() {","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/netty/src/main/java/io/grpc/netty/NettyServer.java#L325-L361","documentation":"NettyServer.start() binds all configured listen addresses via Netty. If the aggregate bind future is unsuccessful (e.g. the very first phase of binding fails such that no per-address future can be inspected), the server closes any channels it created and throws IOException \"Failed to bind to addresses <addresses>\" with the underlying bind cause attached.","triggerScenarios":"Calling start() on a NettyServer whose bind call fails overall — most commonly a port already in use (BindException), or binding to an address/interface that does not exist or is not permitted.","commonSituations":"Another process (or a previous non-terminated instance) already holds the port; running without privileges on a privileged port (<1024); binding to a specific interface IP that isn't assigned; SO_REUSEADDR misconfiguration across platforms.","solutions":["Read the cause (usually java.net.BindException: Address already in use) and free the port: kill the conflicting process or change the port.","Bind to 0.0.0.0 / a wildcard address or a valid interface IP.","Check `lsof -i :<port>` / `netstat -tlnp` to identify the holder of the port.","Use an unprivileged port or run with appropriate capabilities for privileged ports.","Handle the IOException in start() callers with retry/backoff for transient port conflicts."],"exampleFix":"// before\nServer server = NettyServerBuilder.forPort(80).addService(impl).build().start(); // privileged/conflicted port\n// after\nServer server = NettyServerBuilder.forPort(8080).addService(impl).build();\ntry {\n  server.start();\n} catch (IOException e) {\n  // pick alternate port or log bind failure (e.getCause() has BindException)\n}","handlingStrategy":"try-catch","validationCode":"int port = 50051;\ntry (java.net.ServerSocket probe = new java.net.ServerSocket(port)) { /* port free */ } catch (java.net.BindException e) { port = 0; }","typeGuard":null,"tryCatchPattern":"try {\n  server.start();\n} catch (IOException e) {\n  if (e.getCause() instanceof java.net.BindException) {\n    // port in use: choose another port or stop the conflicting process\n  }\n  throw e;\n}","preventionTips":["Use port 0 (ephemeral) or check port availability before start()","Ensure old server instances call shutdown() in tests","Avoid privileged ports below 1024 without root"],"tags":["grpc","java","network","bind","ioexception"],"backgroundTag":"address-already-in-use","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}