{"record":{"id":"744a65ed523a34a1","repo":"grpc/grpc-java","slug":"failed-to-bind-to-address-address","errorCode":null,"errorMessage":"Failed to bind to address ${address}","messagePattern":"Failed to bind to address (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"netty/src/main/java/io/grpc/netty/NettyServer.java","lineNumber":354,"sourceCode":"        }\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() {\n        @Override\n        public void operationComplete(ChannelFuture future) throws Exception {\n          channelz.removeListenSocket(listenSocketStats);\n        }\n      });\n    }\n    listenSocketStatsList = Collections.unmodifiableList(socketStats);\n  }\n\n  @Override\n  public void shutdown() {","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/netty/src/main/java/io/grpc/netty/NettyServer.java#L336-L372","documentation":"After the batch bind completes, NettyServer.start() inspects each individual bind future. If a particular address's future failed, all channels are closed and an IOException \"Failed to bind to address <address>\" is thrown with that future's cause. This pinpoints which single address failed when multiple addresses were requested.","triggerScenarios":"Calling start() where one of the configured listen addresses fails to bind — per-address BindException (port in use), unreachable/unassigned interface address, or permission denied on a privileged port — while the overall bind call still returned futures to inspect.","commonSituations":"Multi-address servers where only one of several ports is occupied; binding to a specific local IP that is currently down; container environments where the requested interface doesn't exist; race where another process grabbed the port between check and bind.","solutions":["Read the cause from the IOException (typically BindException) to see why that address failed.","Free the conflicting port or pick a different one; verify each address exists on the host.","Use wildcard binding (0.0.0.0 or a port of 0 to get an ephemeral port) where feasible.","Check interface availability inside containers/VMs before binding to a specific IP."],"exampleFix":"// before\nserverBuilder.addListenAddress(new InetSocketAddress(\"10.0.0.99\", 50051)); // IP not assigned to host\n// after\nserverBuilder.addListenAddress(new InetSocketAddress(\"0.0.0.0\", 50051));\nServer server = serverBuilder.build();\ntry {\n  server.start();\n} catch (IOException e) {\n  // e.getCause() explains which address failed and why\n}","handlingStrategy":"try-catch","validationCode":"for (SocketAddress a : addresses) {\n  if (a instanceof InetSocketAddress && ((InetSocketAddress) a).getAddress() != null\n      && !((InetSocketAddress) a).getAddress().isAnyLocalAddress()) {\n    // verify the interface IP exists on this host before binding\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  server.start();\n} catch (IOException e) {\n  // e.getMessage() names the failing address; e.getCause() has the bind reason\n  throw new RuntimeException(\"Server failed to start: \" + e.getMessage(), e);\n}","preventionTips":["Bind to 0.0.0.0 unless a specific interface is required","Verify each listen address/IP exists on the host (ip addr)","Use unique ports per test server to avoid cross-test conflicts"],"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"}