{"record":{"id":"6409b1e9a8390440","repo":"t8y2/dbx","slug":"decode-zookeeper-protocol-version-w","errorCode":null,"errorMessage":"decode ZooKeeper protocol version: %w","messagePattern":"decode ZooKeeper protocol version: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/argo-go/zookeeper_protocol.go","lineNumber":164,"sourceCode":"\t\ttimeout = defaultConnectTimeout\n\t}\n\tclient := &protocolZooKeeperClient{connection: connection, timeout: timeout}\n\trequest := &zooKeeperEncoder{}\n\trequest.int32(zooKeeperProtocolVersion)\n\trequest.int64(0)\n\trequest.int32(zooKeeperTimeoutMillis(timeout))\n\trequest.int64(0)\n\trequest.bytes(make([]byte, 16))\n\tif err := client.writeFrame(request.data()); err != nil {\n\t\treturn nil, fmt.Errorf(\"send ZooKeeper connect request: %w\", err)\n\t}\n\tresponse, err := client.readFrame()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"read ZooKeeper connect response: %w\", err)\n\t}\n\tdecoder := newZooKeeperDecoder(response)\n\tif _, err := decoder.int32(); err != nil {\n\t\treturn nil, fmt.Errorf(\"decode ZooKeeper protocol version: %w\", err)\n\t}\n\tif _, err := decoder.int32(); err != nil {\n\t\treturn nil, fmt.Errorf(\"decode ZooKeeper session timeout: %w\", err)\n\t}\n\tsessionID, err := decoder.int64()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"decode ZooKeeper session ID: %w\", err)\n\t}\n\tif _, err := decoder.bytes(); err != nil {\n\t\treturn nil, fmt.Errorf(\"decode ZooKeeper session password: %w\", err)\n\t}\n\tif sessionID == 0 {\n\t\treturn nil, zk.ErrSessionExpired\n\t}\n\treturn client, nil\n}\n\nfunc zooKeeperTimeoutMillis(timeout time.Duration) int32 {","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/argo-go/zookeeper_protocol.go#L146-L182","documentation":"The connect response must decode as an int32 protocol version; if newZooKeeperDecoder.int32() cannot read 4 bytes from the response frame, this error is returned. It means the server sent a frame too short or not matching the ZooKeeper ConnectResponse layout — a protocol mismatch rather than a network failure.","triggerScenarios":"newProtocolZooKeeperClient reading a response frame whose payload has fewer than 4 bytes, or bytes produced by a non-ZooKeeper protocol (e.g. connecting to an HTTP endpoint or a TLS listener in plaintext, or vice versa), making the first int32 decode fail.","commonSituations":"Port mixups (TLS client to a plaintext port or the reverse); ZooKeeper version speaking an unexpected wire format through a broker; a proxy returning an error page/banner that got framed as the response; unit-test fakes writing malformed responses.","solutions":["Verify TLS settings match the server: use the TLS dial path only for a TLS-enabled listener and plaintext otherwise","Confirm the endpoint is a real ZooKeeper client port (2181/2281) and not an admin/HTTP port","Capture the raw response frame to identify what the server actually sent","Check ZooKeeper client/server version compatibility for the connect response layout"],"exampleFix":"// before\naddr := \"zk1.example.com:2181\" // server actually requires TLS on 2281\nconn := connectTLS(addr)\n// after\naddr := \"zk1.example.com:2281\" // TLS client port\nconn := connectTLS(addr)","handlingStrategy":"validation","validationCode":"func looksLikeZKConnectResponse(frame []byte) bool {\n    return len(frame) >= 4 // protocol version int32 is the first field\n}","typeGuard":"func hasMinConnectResponse(frame []byte) bool { return len(frame) >= 4 }","tryCatchPattern":"client, err := newProtocolZooKeeperClient(conn, timeout)\nif err != nil {\n    if strings.Contains(err.Error(), \"decode ZooKeeper protocol version\") {\n        return fmt.Errorf(\"endpoint %s does not speak the ZooKeeper protocol; check TLS vs plaintext port\", address)\n    }\n    return err\n}","preventionTips":["Match TLS client settings to TLS-enabled listener ports (2181 plaintext vs 2281 TLS)","Smoke-test the raw protocol against each endpoint during deploys","Check version compatibility between client library and ZooKeeper server","Bypass suspicious proxies when diagnosing decode failures"],"tags":["zookeeper","protocol","decoding"],"backgroundTag":"protocol-decode-failed","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}