t8y2/dbx · error

ZooKeeper request failed with error code

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.

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

// 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
}

_, _, 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)
    }
}

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

• {candidate.name} {method}: {json.dumps(response['error'])}
• Unknown method
• ZooKeeper request failed with error code
• ZooKeeper SASL server returned error
• agent exited before

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

Appendix: 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)