{"record":{"id":"db5d25edfb060c53","repo":"t8y2/dbx","slug":"zookeeper-request-failed-with-error-code-d-db5d25","errorCode":null,"errorMessage":"ZooKeeper request failed with error code %d","messagePattern":"ZooKeeper request failed with error code (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/hive-go/zookeeper_protocol.go","lineNumber":403,"sourceCode":"\nfunc zooKeeperError(code int32) error {\n\tswitch code {\n\tcase 0:\n\t\treturn nil\n\tcase -4:\n\t\treturn zk.ErrConnectionClosed\n\tcase -101:\n\t\treturn zk.ErrNoNode\n\tcase -102:\n\t\treturn zk.ErrNoAuth\n\tcase -112:\n\t\treturn zk.ErrSessionExpired\n\tcase -115:\n\t\treturn zk.ErrAuthFailed\n\tcase -124:\n\t\treturn errZooKeeperSessionClosedRequiresSASL\n\tdefault:\n\t\treturn fmt.Errorf(\"ZooKeeper request failed with error code %d\", code)\n\t}\n}\n\ntype zooKeeperEncoder struct {\n\tbuffer bytes.Buffer\n}\n\nfunc (encoder *zooKeeperEncoder) int32(value int32) {\n\tvar data [4]byte\n\tbinary.BigEndian.PutUint32(data[:], uint32(value))\n\tencoder.buffer.Write(data[:])\n}\n\nfunc (encoder *zooKeeperEncoder) int64(value int64) {\n\tvar data [8]byte\n\tbinary.BigEndian.PutUint64(data[:], uint64(value))\n\tencoder.buffer.Write(data[:])\n}","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/hive-go/zookeeper_protocol.go#L385-L421","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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)."],"exampleFix":"// before\n_, err := zkClient.Set(path, data, -1) // concurrent writer bumped version -> code -103\n// after\nstat, _ := zkClient.Exists(path)\n_, err := zkClient.Set(path, data, stat.Version) // use CAS version or retry on badVersion","handlingStrategy":"try-catch","validationCode":"// pre-flight: check the znode exists and its ACL allows your auth identity\nstat, err := client.Exists(path)\nif err != nil || !stat { log.Fatalf(\"znode %s missing or check failed\", path) }","typeGuard":"func isZKErrorCode(err error, code int) bool {\n\tvar msg string\n\tif err != nil { msg = err.Error() }\n\treturn strings.Contains(msg, fmt.Sprintf(\"error code %d\", code))\n}","tryCatchPattern":"_, err := client.Set(path, data, version)\nif err != nil {\n\tswitch {\n\tcase isZKErrorCode(err, -101): // noauth: fix SASL/ACL config\n\t\treauthenticate(client)\n\tcase isZKErrorCode(err, -103): // badVersion: refetch and retry\n\t\tstat, _ := client.Exists(path)\n\t\t_, err = client.Set(path, data, stat.Version)\n\tdefault:\n\t\treturn fmt.Errorf(\"zk set %s: %w\", path, err)\n\t}\n}","preventionTips":["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."],"tags":["zookeeper","error-code","server-response","unmapped-code"],"backgroundTag":"zookeeper-error-code","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}