apache/hadoop · error · IOException

"There is already a listener binding to: " + auxiliaryPort

Error message

"There is already a listener binding to: " + auxiliaryPort

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java:3531

      } else if (UserGroupInformation.isLoginTicketBased()) {
        UserGroupInformation.getLoginUser().forceReloginFromTicketCache();
      }
    } else {
      if (UserGroupInformation.isLoginKeytabBased()) {
        UserGroupInformation.getLoginUser().reloginFromKeytab();
      } else if (UserGroupInformation.isLoginTicketBased()) {
        UserGroupInformation.getLoginUser().reloginFromTicketCache();
      }
    }
  }

  public synchronized void addAuxiliaryListener(int auxiliaryPort)
      throws IOException {
    if (auxiliaryListenerMap == null) {
      auxiliaryListenerMap = new HashMap<>();
    }
    if (auxiliaryListenerMap.containsKey(auxiliaryPort) && auxiliaryPort != 0) {
      throw new IOException(
          "There is already a listener binding to: " + auxiliaryPort);
    }
    Listener newListener = new Listener(auxiliaryPort);
    newListener.setIsAuxiliary();

    // in the case of port = 0, the listener would be on a != 0 port.
    LOG.info("Adding a server listener on port " +
        newListener.getAddress().getPort());
    auxiliaryListenerMap.put(newListener.getAddress().getPort(), newListener);
  }

  private RpcSaslProto buildNegotiateResponse(List<AuthMethod> authMethods)
      throws IOException {
    RpcSaslProto.Builder negotiateBuilder = RpcSaslProto.newBuilder();
    if (authMethods.contains(AuthMethod.SIMPLE) && authMethods.size() == 1) {
      // SIMPLE-only servers return success in response to negotiate
      negotiateBuilder.setState(SaslState.SUCCESS);
    } else {

View on GitHub (pinned to 2add963021)

Solutions

1. 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)
2. Track ports you have already added (or query your own state) and skip re-adding before calling addAuxiliaryListener
3. Stop/tear down the Server instance before rebuilding its auxiliary listeners on the same fixed ports
4. Fix the double-initialization path that invokes setup twice

Example fix

// before: repeated call with a fixed port
server.addAuxiliaryListener(8020); // second time -> IOException

// after: guard the port, or use an ephemeral port
if (!addedPorts.contains(auxPort)) {
  server.addAuxiliaryListener(auxPort);
  addedPorts.add(auxPort);
}
// or simply: server.addAuxiliaryListener(0); // OS-assigned port

// track added auxiliary ports before calling the API
private final Set<Integer> auxPorts = new HashSet<>();
public void addAuxListener(RPC.Server server, int port) throws IOException {
  int effective = (port == 0 || auxPorts.contains(port)) ? 0 : port;
  if (port != 0 && auxPorts.contains(port)) {
    LOG.warn("Auxiliary listener on port {} already exists; binding ephemeral", port);
  }
  server.addAuxiliaryListener(effective);
  auxPorts.add(effective);
}

try {
  server.addAuxiliaryListener(auxPort);
} catch (IOException e) {
  if (e.getMessage().contains("already a listener binding to")) {
    // duplicate setup: either reuse the existing listener or pick a new/ephemeral port
    LOG.warn("Auxiliary port {} already bound; skipping re-add", auxPort);
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Client sent unsupported state ${state}
• Client did not send a token
• "Unexpected data length " + dataLength + "!! from " + getHos
• "Requested data length " + dataLength + " is longer than max
• FATAL_DESERIALIZING_REQUEST

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/d5037fb67c06c14b. Report an issue: GitHub.