What causes "checksum error:%s %s" in XX-net/XX-Net?

Retry — single checksum mismatch only fails that transfer

checksum error:%s %s

Error message

checksum error:%s %s

What it means

MD5 integrity check failed: the checksum in the last 32 bytes of the received content does not match md5(content[:-32]). The transfer is marked 'timeout' and retried later; it is not fatal to the session.

Source

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

                # xlog.debug("target roundtrip: %d, on_road: %d", self.target_on_roads, self.on_road_num)

                if rtt > 8000:
                    xlog.warn("rtt:%d speed:%d trace:%s", rtt, speed, response.worker.get_trace())
                    xlog.warn("task trace:%s", response.task.get_trace())
                    g.stat["slow_roundtrip"] += 1

                data = payload.get_buf(data_len)
                ack = payload.get_buf(ack_len)
                rcvd_no_list = payload.get_buf(rcvd_no_len)
                sent_no_list = payload.get_buf(sent_no_len)
                unack_snd_sn = payload.get_buf(unack_snd_sn_len)
                ext = payload.get_buf(ext_len)

                if len(payload) > 32:
                    checksum_str = utils.to_str(payload.get(32).tobytes())
                    checksum = hashlib.md5(bytes(content[:-32])).hexdigest()
                    if checksum != checksum_str:
                        xlog.warn("checksum error:%s %s", checksum_str, checksum)

                        data_info["stat"] = "timeout"
                        continue

                self.last_receive_time = time.time()

                with self.lock:
                    if transfer_no in self.transfer_list:
                        del self.transfer_list[transfer_no]

                self.round_trip_process(data, ack, rcvd_no_list, sent_no_list, unack_snd_sn, server_time)
                self.check_upload_not_acked(server_time)

                if self.on_road_num + 1 < self.target_on_roads:
                    self.wait_queue.notify()

                self.wait_queue.notify()
                return

View on GitHub (pinned to cfa5bc17b6)

Solutions

Retry — single checksum mismatch only fails that transfer
Improve connection stability / try a different network path
Update XX-Net to match server framing version
If persistent for all responses, capture traffic and report framing bug

Defensive patterns

Strategy: retry

Prevention

Treat checksum-failed transfers as retries, not fatal errors
Maintain stable network paths to reduce corruption
Update client when server framing changes

When it happens

Trigger: Response body corrupted in transit (truncation, bit flips), or a server/payload format change where the trailing 32-byte checksum assumption no longer holds.

Common situations: Unstable connections, aggressive DPI/middlebox tampering, proxy rewrites, or client/server version mismatch changing frame layout.

Related errors

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