What causes "ZooKeeper request failed with error code %d" in t8y2/dbx?

Log/inspect the numeric code in the message and look it up in the ZooKeeper Programmer's Guide error code table.

ZooKeeper request failed with error code %d

Error message

ZooKeeper request failed with error code %d

What it means

zooKeeperError maps ZooKeeper wire-protocol error codes to Go sentinel errors (e.g. session expired, auth failed, closed-session-requires-SASL). Codes without a known mapping fall through to this generic error carrying the raw numeric code. The library throws it whenever a request's server response reports a non-zero, unmapped error code.

Source

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

func zooKeeperError(code int32) error {
	switch code {
	case 0:
		return nil
	case -4:
		return zk.ErrConnectionClosed
	case -101:
		return zk.ErrNoNode
	case -102:
		return zk.ErrNoAuth
	case -112:
		return zk.ErrSessionExpired
	case -115:
		return zk.ErrAuthFailed
	case -124:
		return errZooKeeperSessionClosedRequiresSASL
	default:
		return fmt.Errorf("ZooKeeper request failed with error code %d", code)
	}
}

type zooKeeperEncoder struct {
	buffer bytes.Buffer
}

func (encoder *zooKeeperEncoder) int32(value int32) {
	var data [4]byte
	binary.BigEndian.PutUint32(data[:], uint32(value))
	encoder.buffer.Write(data[:])
}

func (encoder *zooKeeperEncoder) int64(value int64) {
	var data [8]byte
	binary.BigEndian.PutUint64(data[:], uint64(value))
	encoder.buffer.Write(data[:])
}

View on GitHub (pinned to c0390bff16)

Solutions

Log/inspect the numeric code in the message and look it up in the ZooKeeper Programmer's Guide error code table.
Check ACLs on the target znode and the client's auth scheme (digest/SASL); add credentials or chattr the node.
For session-related codes, reconnect and re-establish the session rather than retrying on the dead session.
If the code is a valid ZooKeeper error not yet mapped, add a case in zooKeeperError to return a specific sentinel error.
Verify client and server versions are compatible (newer server versions can emit codes the old client doesn't map).

Example fix

// before
_, err := zkClient.Set(path, data, -1) // concurrent writer bumped version -> code -103
// after
stat, _ := zkClient.Exists(path)
_, err := zkClient.Set(path, data, stat.Version) // use CAS version or retry on badVersion

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: check the znode exists and its ACL allows your auth identity
stat, err := client.Exists(path)
if err != nil || !stat { log.Fatalf("znode %s missing or check failed", path) }

Type guard

func isZKErrorCode(err error, code int) bool {
	var msg string
	if err != nil { msg = err.Error() }
	return strings.Contains(msg, fmt.Sprintf("error code %d", code))
}

Try / catch

_, err := client.Set(path, data, version)
if err != nil {
	switch {
	case isZKErrorCode(err, -101): // noauth: fix SASL/ACL config
		reauthenticate(client)
	case isZKErrorCode(err, -103): // badVersion: refetch and retry
		stat, _ := client.Exists(path)
		_, err = client.Set(path, data, stat.Version)
	default:
		return fmt.Errorf("zk set %s: %w", path, err)
	}
}

Prevention

Map the numeric code in the message to ZooKeeper's documented error table before deciding how to react.
Set ACLs explicitly when creating znodes and grant the client's principal the needed permissions.
Use compare-and-set versions (not -1) for writes to avoid concurrent-update codes.
Keep client and server ZooKeeper versions aligned so all codes are mapped.
Never blindly retry: session or auth codes require reconnection/re-auth, not a retry.

When it happens

Trigger: Any request() call whose ZooKeeper response carries an error code not among the explicitly mapped cases (e.g. -110 session expired is mapped, but codes like MarathonAPIError-style or server-specific codes are not).

Common situations: Server rejecting operations due to ACL/permissions on a node, node version conflicts (badVersion) during concurrent writes, quota violations, unmapped codes from newer ZooKeeper versions, or noauth errors when SASL is required but the client wasn't configured for it.

Related errors

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