t8y2/dbx · error

ZooKeeper response XID %d does not match request XID %d

Error message

ZooKeeper response XID %d does not match request XID %d

What it means

Returned by protocolZooKeeperClient.request when the xid in a ZooKeeper response frame does not equal the xid of the request that was sent. On a single connection responses must match requests in order; an xid mismatch indicates a protocol/stream desynchronization (concurrent use of the connection or a server bug).

Source

Thrown at agents/drivers/hive-go/zookeeper_protocol.go:323

	request.int32(client.xid)
	request.int32(opcode)
	if encodeBody != nil {
		encodeBody(request)
	}
	if err := client.writeFrame(request.data()); err != nil {
		return nil, err
	}
	response, err := client.readFrame()
	if err != nil {
		return nil, err
	}
	decoder := newZooKeeperDecoder(response)
	xid, err := decoder.int32()
	if err != nil {
		return nil, err
	}
	if xid != client.xid {
		return nil, fmt.Errorf("ZooKeeper response XID %d does not match request XID %d", xid, client.xid)
	}
	if _, err := decoder.int64(); err != nil {
		return nil, err
	}
	code, err := decoder.int32()
	if err != nil {
		return nil, err
	}
	if err := zooKeeperError(code); err != nil {
		return nil, err
	}
	return decoder.remaining(), nil
}

func (client *protocolZooKeeperClient) writeFrame(payload []byte) error {
	if len(payload) > zooKeeperMaxFrameSize {
		return fmt.Errorf("ZooKeeper request frame is %d bytes, maximum is %d", len(payload), zooKeeperMaxFrameSize)
	}

View on GitHub (pinned to c0390bff16)

Solutions

1. Ensure the client connection is used by a single goroutine/operation at a time as the driver intends
2. Retry the operation on a fresh connection if desynchronization is transient
3. Check the ZooKeeper server version for known wire-protocol issues

When it happens

Trigger: Thrown at agents/drivers/hive-go/zookeeper_protocol.go:323 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/60177fad51046216. Report an issue: GitHub.