XX-net/XX-Net · error

do_unwrap_socks connect to x-tunnel for %s:%d proxy fail.

Error message

do_unwrap_socks connect to x-tunnel for %s:%d proxy fail.

What it means

do_unwrap_socks could not create a SOCKS5 connection to the local x-tunnel SOCKS entry (127.0.0.1:g.x_tunnel_socks_port) within 15s; the unwrap attempt is abandoned.

Source

Thrown at code/default/smart_router/local/smart_route.py:271

        raise XTunnelNotRunning()

    # xlog.debug("do_socks %r connect to %s:%d conn_id:%d", client_address, host, port, conn_id)
    if left_buf:
        g.x_tunnel.global_var.session.conn_list[conn_id].transfer_received_data(left_buf)
    g.x_tunnel.global_var.session.conn_list[conn_id].start(block=True)


def do_unwrap_socks(sock, host, port, client_address, req, left_buf=b""):
    if not g.x_tunnel:
        return

    try:
        remote_sock = socks.create_connection(
            (host, port),
            proxy_type="socks5h", proxy_addr="127.0.0.1", proxy_port=g.x_tunnel_socks_port, timeout=15
        )
    except Exception as e:
        xlog.warn("do_unwrap_socks connect to x-tunnel for %s:%d proxy fail.", host, port)
        return

    if isinstance(req.connection, ssl.SSLSocket):
        try:
            remote_ssl_sock = ssl_context.wrap_socket(remote_sock, server_hostname=host)
        except:
            xlog.warn("do_unwrap_socks ssl_wrap for %s:%d proxy fail.", host, port)
            return
    else:
        remote_ssl_sock = remote_sock

    # avoid close by req.__del__
    req.rfile._close = False
    req.wfile._close = False
    req.connection = None

    if not isinstance(sock, SocketWrap):
        sock = SocketWrap(sock, client_address[0], client_address[1])

View on GitHub (pinned to cfa5bc17b6)

Solutions

  1. Confirm the x-tunnel client is running and its SOCKS port matches g.x_tunnel_socks_port
  2. Check the port is listening: ss -lntp | grep <port>
  3. Restart x-tunnel if the listener died
  4. Raise the 15s timeout on slow machines if startup is racing
Defensive patterns

Strategy: retry

Validate before calling

import socket as s; s.create_connection(('127.0.0.1', port), 1)  # probe listener first

Try / catch

Retry create_connection once after short delay; fall back to other rules on second failure.

Prevention

When it happens

Trigger: socks.create_connection to 127.0.0.1:x_tunnel_socks_port fails: the local x-tunnel SOCKS listener is not running, wrong port, or connect timeout (15s).

Common situations: x-tunnel SOCKS component not started, port misconfigured in g.x_tunnel_socks_port, firewall/loopback restrictions, x-tunnel process crashed.

Related errors

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