Skip to content

HTTPServer on port 0 can fail with EADDRINUSE because socketserver sets SO_REUSEADDR #162256

Description

@nyh

Bug report

On Linux, http.server.HTTPServer(('127.0.0.1', 0), handler), which asks the kernel for a free port, can fail with OSError: [Errno 98] Address already in use. Because HTTPServer sets SO_REUSEADDR, another program that also sets SO_REUSEADDR can bind the very same port between our bind() and our listen(), and if it listens first, our listen() fails.

We hit this in a test suite that runs many such servers in parallel with Docker or Podman containers, whose port forwarders are written in Go, which sets SO_REUSEADDR on every listener.

Reproducer, which plays both programs in this race:

import socket
from http.server import HTTPServer, BaseHTTPRequestHandler

# Do what HTTPServer.__init__ does, in two steps, to show the window between them.
srv = HTTPServer(('127.0.0.1', 0), BaseHTTPRequestHandler, bind_and_activate=False)
srv.server_bind()        # sets SO_REUSEADDR, binds a kernel-picked port
port = srv.server_address[1]

# Another program that sets SO_REUSEADDR binds the same port during the
# window, and listens first:
other = socket.socket()
other.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
other.bind(('0.0.0.0', port))
other.listen()

srv.server_activate()    # OSError: [Errno 98] Address already in use

Why it happens: on Linux, SO_REUSEADDR lets two sockets bind the same address and port as long as neither of them listens yet. SO_REUSEADDR is useful for re-binding a fixed port that still has connections in TIME_WAIT, but it does nothing useful for port 0, because the kernel only hands out ports that aren't in use. For a port-0 server, its only effect is to open this race window. HTTPServer also makes the window wider than it needs to be: HTTPServer.server_bind() calls socket.getfqdn(host), a reverse DNS lookup, after bind() and before listen(). I measured a few milliseconds for the first lookup of 127.0.0.1 in a fresh process, and with a slow resolver it can take much longer.

xmlrpc.server.SimpleXMLRPCServer and the server of logging.config.listen() also set allow_reuse_address = True and are used with port 0 (CPython's own tests do it), so they have the same bug, though without the getfqdn() call their window is much shorter.

Proposed fix: TCPServer.server_bind() shouldn't set SO_REUSEADDR when binding port 0 of AF_INET/AF_INET6, much as it already checks the address family before setting SO_REUSEPORT:

        if (self.allow_reuse_address and hasattr(socket, "SO_REUSEADDR")
                and not (self.address_family in (socket.AF_INET, socket.AF_INET6)
                         and self.server_address[1] == 0)):
            self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)

With this change, the port is ours from the moment bind() returns: in the reproducer above, it is the other program's bind() that fails, and our server comes up normally. Moving HTTPServer's getfqdn() call after listen() would only narrow the window, and would change when subclasses see server_name set, so the change above seems the better fix.

Related: gh-85307 (on Windows, HTTPServer's SO_REUSEADDR lets two servers bind the same port).

CPython versions tested on:

3.14

Operating systems tested on:

Linux

Linked PRs

Activity

  1. added
    type-bugAn unexpected behavior, bug, or error
    on Nov 19, 2026
  2. added a commit that references this issue on Nov 19, 2026
  3. added
    stdlibStandard Library Python modules in the Lib/ directory
    topic-socketRelated to the socket, socketserver and selectors modules
    on Nov 19, 2026
  4. added a commit that references this issue on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    stdlibStandard Library Python modules in the Lib/ directorytopic-socketRelated to the socket, socketserver and selectors modulestype-bugAn unexpected behavior, bug, or error

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions