t8y2/dbx · error

ZooKeeper request failed with error code %d

Error message

ZooKeeper request failed with error code %d

What it means

The ZooKeeper server returned a non-zero error code (RC) in a response header, and the code is not one of the ones this driver maps to a specific sentinel (ConnectionClosed, NoNode, NoAuth, SessionExpired, AuthFailed, SASL-required). zooKeeperError wraps it as a generic error carrying the raw integer code so the caller can still see what the server said.

Source

Thrown at agents/drivers/argo-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

  1. Log the full error including the numeric code and look it up in the ZooKeeper documentation — the code identifies the exact server-side condition.
  2. For code -100 (NodeExists), check existence first or add an exists-and-reconcile path around Create; for create-if-absent semantics retry the operation on -100.
  3. For -110 (ConnectionLoss), make the operation idempotent and retry with backoff on a reconnected client.
  4. For -111/-112 session issues, ensure only one client instance uses a given session (don't share chroot/credentials across processes) and re-create the client on session loss.
  5. If the code is a valid server error not mapped by this driver, extend zooKeeperError's switch to map it to a sentinel.

Example fix

// before
_, _, err := zkClient.Create(path, data, 0, acl)

// after
_, _, err := zkClient.Create(path, data, zk.FlagEphemeral, acl)
if err == zk.ErrNodeExists {
    _, statErr := zkClient.Set(path, data, -1) // reconcile instead of failing
    return statErr
}
return err
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check for the most common code (-100 NodeExists)
exists, _, err := zkClient.Exists(path)
if err != nil {
    return err
}
if exists && createOnce {
    return nil // already created, nothing to do
}

Try / catch

_, _, err := client.request(payload)
var zkErr *zkError
if errors.As(err, &zkErr) {
    switch zkErr.code {
    case -100: // NodeExists: reconcile
    case -110, -111: // ConnectionLoss/SessionMoved: re-dial and retry idempotently
    case -112: // SessionExpired: rebuild the client and session
    default:
        log.Errorf("zookeeper error code %d", zkErr.code)
    }
}

Prevention

When it happens

Trigger: Any request (Get/Set/Create/Delete/Children) where the server replies with an unmapped RC: e.g. -110 ConnectionLoss (connection dropped mid-request), -100 NodeExists when creating an existing node, -111 SessionMoved, -119 AuthFailed variants, or any future/new server error code this driver doesn't recognize.

Common situations: Hitting NodeExists (code -100) because Create is called without EPHEMERAL handling or after a retry re-ran a successful create; SessionMoved when two clients share one session (forked process or duplicated credentials); ConnectionLoss during network blips or GC pauses on the server; upgrading ZooKeeper servers to a version emitting codes this driver predates.

Related errors

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