{"record":{"id":"d5037fb67c06c14b","repo":"apache/hadoop","slug":"there-is-already-a-listener-binding-to-auxil","errorCode":null,"errorMessage":"\"There is already a listener binding to: \" + auxiliaryPort","messagePattern":"\"There is already a listener binding to: \" \\+ auxiliaryPort","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java","lineNumber":3531,"sourceCode":"      } else if (UserGroupInformation.isLoginTicketBased()) {\n        UserGroupInformation.getLoginUser().forceReloginFromTicketCache();\n      }\n    } else {\n      if (UserGroupInformation.isLoginKeytabBased()) {\n        UserGroupInformation.getLoginUser().reloginFromKeytab();\n      } else if (UserGroupInformation.isLoginTicketBased()) {\n        UserGroupInformation.getLoginUser().reloginFromTicketCache();\n      }\n    }\n  }\n\n  public synchronized void addAuxiliaryListener(int auxiliaryPort)\n      throws IOException {\n    if (auxiliaryListenerMap == null) {\n      auxiliaryListenerMap = new HashMap<>();\n    }\n    if (auxiliaryListenerMap.containsKey(auxiliaryPort) && auxiliaryPort != 0) {\n      throw new IOException(\n          \"There is already a listener binding to: \" + auxiliaryPort);\n    }\n    Listener newListener = new Listener(auxiliaryPort);\n    newListener.setIsAuxiliary();\n\n    // in the case of port = 0, the listener would be on a != 0 port.\n    LOG.info(\"Adding a server listener on port \" +\n        newListener.getAddress().getPort());\n    auxiliaryListenerMap.put(newListener.getAddress().getPort(), newListener);\n  }\n\n  private RpcSaslProto buildNegotiateResponse(List<AuthMethod> authMethods)\n      throws IOException {\n    RpcSaslProto.Builder negotiateBuilder = RpcSaslProto.newBuilder();\n    if (authMethods.contains(AuthMethod.SIMPLE) && authMethods.size() == 1) {\n      // SIMPLE-only servers return success in response to negotiate\n      negotiateBuilder.setState(SaslState.SUCCESS);\n    } else {","sourceCodeStart":3513,"sourceCodeEnd":3549,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java#L3513-L3549","documentation":"addAuxiliaryListener() attaches an extra RPC listener (used e.g. for separate client channels) and tracks them by port in auxiliaryListenerMap. Calling it twice with the same non-zero port throws IOException because only one listener may bind a given port. Passing 0 is always allowed since the OS picks an ephemeral port.","triggerScenarios":"Server initialization code invokes addAuxiliaryListener(port) twice with the same explicit port — double init, restart-without-cleanup paths, or repeated service refresh; tests that rebuild servers against a fixed port without stopping the previous one.","commonSituations":"Embedded/auxiliary RPC listeners (e.g. dedicated admin or replication channels) wired by custom services; reconfiguration code that re-runs listener setup; unit tests that call setup() multiple times on the same Server instance.","solutions":["Pass 0 to let the server bind an ephemeral port, then read the actual port from the listener address (it is logged and stored in the map)","Track ports you have already added (or query your own state) and skip re-adding before calling addAuxiliaryListener","Stop/tear down the Server instance before rebuilding its auxiliary listeners on the same fixed ports","Fix the double-initialization path that invokes setup twice"],"exampleFix":"// before: repeated call with a fixed port\nserver.addAuxiliaryListener(8020); // second time -> IOException\n\n// after: guard the port, or use an ephemeral port\nif (!addedPorts.contains(auxPort)) {\n  server.addAuxiliaryListener(auxPort);\n  addedPorts.add(auxPort);\n}\n// or simply: server.addAuxiliaryListener(0); // OS-assigned port","handlingStrategy":"validation","validationCode":"// track added auxiliary ports before calling the API\nprivate final Set<Integer> auxPorts = new HashSet<>();\npublic void addAuxListener(RPC.Server server, int port) throws IOException {\n  int effective = (port == 0 || auxPorts.contains(port)) ? 0 : port;\n  if (port != 0 && auxPorts.contains(port)) {\n    LOG.warn(\"Auxiliary listener on port {} already exists; binding ephemeral\", port);\n  }\n  server.addAuxiliaryListener(effective);\n  auxPorts.add(effective);\n}","typeGuard":null,"tryCatchPattern":"try {\n  server.addAuxiliaryListener(auxPort);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"already a listener binding to\")) {\n    // duplicate setup: either reuse the existing listener or pick a new/ephemeral port\n    LOG.warn(\"Auxiliary port {} already bound; skipping re-add\", auxPort);\n  } else { throw e; }\n}","preventionTips":["Pass 0 for an ephemeral port when the exact number does not matter","Make setup idempotent: guard repeated init paths with a state flag","Tear down the old Server before rebuilding listeners on fixed ports"],"tags":["rpc","server-setup","port-binding","hadoop-ipc"],"backgroundTag":"port-already-in-use","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}