What causes "proxy handler read error %r" in XX-net/XX-Net?

Generally ignorable — it indicates the client side dropped the connection

proxy handler read error %r

Error message

proxy handler read error %r

What it means

The X-Tunnel local proxy's handle() hit a socket.error while reading the initial SOCKS handshake bytes from the client. The connection is closed after logging. Commonly this is ECONNRESET/ECONNABORTED when the client drops the connection before completing the handshake.

Source

Thrown at code/default/x_tunnel/local/proxy_handler.py:65

            socks_version = self.read_bytes(1)
            if not socks_version:
                return

            if socks_version == b"\x04":
                self.socks4_handler()
            elif socks_version == b"\x05":
                self.socks5_handler()
            elif socks_version == b"C":
                self.https_handler()
            elif socks_version in [b"G", b"P", b"D", b"O", b"H", b"T"]:
                self.http_handler(socks_version)
                return
            else:
                xlog.warn("socks version:%s not supported",  utils.str2hex(socks_version))
                return

        except socket.error as e:
            xlog.warn('proxy handler read error %r', e)
            self.connection.close()
        except Exception as e:
            xlog.exception("proxy handler err:%r", e)
            self.connection.close()

    def read_null_end_line(self):
        sock = self.connection
        sock.setblocking(0)
        try:
            while True:
                n1 = self.read_buffer.find(b"\x00", self.buffer_start)
                if n1 > -1:
                    line = self.read_buffer[self.buffer_start:n1]
                    self.buffer_start = n1 + 1
                    return line

                try:
                    data = sock.recv(8192)

View on GitHub (pinned to cfa5bc17b6)

Solutions

Generally ignorable — it indicates the client side dropped the connection
Filter the log or lower verbosity if noisy
If frequent from real clients, check for middleboxes/NAT resetting the local connections

Defensive patterns

Strategy: try-catch

Try / catch

try:
    handler.handle()
except socket.error as e:
    log_debug('client dropped: %r', e)  # expected from probes

Prevention

Treat early client disconnects as normal; log at debug level
Keep scanners/health checks away from the SOCKS port

When it happens

Trigger: Client connects to the X-Tunnel local proxy port then disconnects immediately (port scan, health check, browser preconnect abandoned), or the underlying socket errors mid-read of the version/method bytes.

Common situations: Port scanners and health checkers probing the proxy port, flaky client networks, clients that close sockets aggressively.

Related errors

AI-assisted analysis of XX-net/XX-Net@cfa5bc17b6 (2026-08-27). Data as JSON: /api/errors/abd17be0e95ad414. Report an issue: GitHub.