What causes "ZooKeeper frame length %d exceeds maximum %d" in t8y2/dbx?

Reduce the payload size — split it across multiple protocol operations if the protocol allows.

ZooKeeper frame length %d exceeds maximum %d

Error message

ZooKeeper frame length %d exceeds maximum %d

What it means

writeZooKeeperFrame refuses to write payloads larger than zooKeeperMaximumFrameLen, since ZooKeeper frames carry a 32-bit length and the client enforces an upper bound for safety. This error means the caller attempted to send an oversized SASL token or payload in a single frame.

Source

Thrown at agents/drivers/zookeeper/sasl.go:172

	header := make([]byte, 4)
	if _, err := io.ReadFull(reader, header); err != nil {
		return nil, err
	}
	length := int(int32(binary.BigEndian.Uint32(header)))
	if length < 0 || length > zooKeeperMaximumFrameLen {
		return nil, fmt.Errorf("ZooKeeper frame length %d is invalid", length)
	}
	payload := make([]byte, length+4)
	copy(payload, header)
	if _, err := io.ReadFull(reader, payload[4:]); err != nil {
		return nil, err
	}
	return payload, nil
}

func writeZooKeeperFrame(writer io.Writer, payload []byte) error {
	if len(payload) > zooKeeperMaximumFrameLen {
		return fmt.Errorf("ZooKeeper frame length %d exceeds maximum %d", len(payload), zooKeeperMaximumFrameLen)
	}
	header := make([]byte, 4)
	binary.BigEndian.PutUint32(header, uint32(len(payload)))
	if err := writeAll(writer, header); err != nil {
		return err
	}
	return writeAll(writer, payload)
}

func writeAll(writer io.Writer, payload []byte) error {
	for len(payload) > 0 {
		written, err := writer.Write(payload)
		if err != nil {
			return err
		}
		if written <= 0 {
			return io.ErrShortWrite
		}

View on GitHub (pinned to c0390bff16)

Solutions

Reduce the payload size — split it across multiple protocol operations if the protocol allows.
Check why the SASL token is so large (unusually large credentials or cipher output) and normalize them.
If the workload legitimately needs larger frames, raise zooKeeperMaximumFrameLen consistently on both sides, respecting the server's jute.maxbuffer.
Log len(payload) at the call site to confirm the actual size against the configured maximum.

Example fix

// before
frame := make([]byte, 0, 10*1024*1024) // 10MB payload
err := writeZooKeeperFrame(w, frame)
// after
if len(frame) > zooKeeperMaximumFrameLen { /* chunk or reject before writing */ }
err := writeZooKeeperFrame(w, frame)

Defensive patterns

Strategy: validation

Validate before calling

if len(payload) > zooKeeperMaximumFrameLen {
	return fmt.Errorf("payload %d exceeds frame limit %d", len(payload), zooKeeperMaximumFrameLen)
}
return writeZooKeeperFrame(writer, payload)

Try / catch

if err := writeZooKeeperFrame(w, payload); err != nil {
	if strings.Contains(err.Error(), "exceeds maximum") {
		return chunkOrCompressPayload(payload)
	}
	return err
}

Prevention

Check payload size before every frame write, not only inside the writer.
Keep application payloads well under zooKeeperMaximumFrameLen (e.g. < 1MB).
Align zooKeeperMaximumFrameLen with the server's jute.maxbuffer if large values are required.

When it happens

Trigger: zooKeeperSASLRound (sending a SASL token) or an anonymous caller invokes writeZooKeeperFrame with len(payload) > zooKeeperMaximumFrameLen.

Common situations: Extremely large SASL tokens from unusual cipher/qop settings, application code batching huge payloads into one frame, or a misconfigured zooKeeperMaximumFrameLen interacting with large tokens.

Related errors

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