What causes "x-tunnel request_balance fail when create_conn:%s" in XX-net/XX-Net?

Check the embedded reason string; if auth-related, correct login_account/login_password in the x_tunnel config.

x-tunnel request_balance fail when create_conn:%s

Error message

x-tunnel request_balance fail when create_conn:%s

What it means

Logged by login_process (invoked from try_loop, roundtrip_task, create_conn) when the session is not yet running (g.server_host empty) and an attempt to (re)authenticate via request_balance fails. The reason string from request_balance explains the underlying failure. create_conn then returns False, so no connection is established this round.

Source

Thrown at code/default/x_tunnel/local/proxy_session.py:1348


login_lock = threading.Lock()


def login_process():
    if not g.session:
        return

    with login_lock:
        if not (g.config.login_account and g.config.login_password):
            xlog.debug("x-tunnel no account")
            return False

        if not g.server_host:
            xlog.debug("session not running, try login..")
            res, reason = request_balance(g.config.login_account, g.config.login_password)
            if not res:
                xlog.warn("x-tunnel request_balance fail when create_conn:%s", reason)
                return False

        if time.time() - g.session.last_send_time > 5 * 60 - 5:
            xlog.info("session timeout, reset it.")
            g.session.stop()

        if g.tls_relay_front:
            g.tls_relay_front.set_x_tunnel_account(g.config.login_account, g.config.login_password)
        if g.seley_front:
            g.seley_front.set_x_tunnel_account(g.config.login_account, g.config.login_password)

        if not g.session.running:
            return g.session.start()

    return True


def create_conn(sock, host, port, log=False):

View on GitHub (pinned to cfa5bc17b6)

Solutions

Check the embedded reason string; if auth-related, correct login_account/login_password in the x_tunnel config.
Confirm network access to the login/balance API host (curl it directly) and fix DNS/proxy issues.
Retry — try_loop will re-attempt login on subsequent iterations; if it never succeeds, inspect firewall rules blocking the API endpoint.
Update XX-Net/x_tunnel if the API endpoint or protocol changed (server-side changes break old clients).

Defensive patterns

Strategy: retry

Prevention

Persist the last good server_host so cold starts still have a session.
Validate credentials at config load time.
Wrap create_conn callers in a retry loop with backoff; treat False as retryable.

When it happens

Trigger: g.server_host is empty (first start or after stop/reset) and request_balance(login_account, login_password) returns a non-True result — network error reaching the balance API, auth rejection, or malformed response. Any caller that needs a connection (roundtrip_task, create_conn, try_loop) hits this.

Common situations: Startup with no cached session, wrong credentials in config, the balance/auth server being unreachable (DNS, GFW interference, outage), or system clock skew breaking auth.

Related errors

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