{"record":{"id":"41704a3fea365bfc","repo":"t8y2/dbx","slug":"connection-timed-out","errorCode":null,"errorMessage":"Connection timed out","messagePattern":"Connection timed out","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/zookeeper/connection.go","lineNumber":213,"sourceCode":"\tconnection, events, err := zk.Connect(\n\t\ttarget.Servers,\n\t\tsessionTimeout,\n\t\tzk.WithDialer(dialer),\n\t\tzk.WithLogInfo(false),\n\t\tzk.WithMaxBufferSize(maxBufferSize),\n\t)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tconnected := false\n\ttimer := time.NewTimer(connectionTimeout)\n\tdefer timer.Stop()\n\tfor !connected {\n\t\tselect {\n\t\tcase event, open := <-events:\n\t\t\tif !open {\n\t\t\t\tconnection.Close()\n\t\t\t\treturn nil, errors.New(\"Connection timed out\")\n\t\t\t}\n\t\t\tif event.State == zk.StateHasSession {\n\t\t\t\tconnected = true\n\t\t\t}\n\t\t\tif event.State == zk.StateAuthFailed {\n\t\t\t\tconnection.Close()\n\t\t\t\treturn nil, errors.New(\"ZooKeeper authentication failed\")\n\t\t\t}\n\t\tcase <-timer.C:\n\t\t\tconnection.Close()\n\t\t\treturn nil, errors.New(\"Connection timed out\")\n\t\t}\n\t}\n\n\tif authScheme == defaultAuthScheme && strings.TrimSpace(config.Username) != \"\" {\n\t\tcredentials := []byte(strings.TrimSpace(config.Username) + \":\" + config.Password)\n\t\tif err := connection.AddAuth(defaultAuthScheme, credentials); err != nil {\n\t\t\tconnection.Close()","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/zookeeper/connection.go#L195-L231","documentation":"openClient watches the session event channel after zk.Connect and waits for zk.StateHasSession. If the event channel closes before a session is established (the zk driver shut down its event loop), or if the overall connectionTimeout timer fires first, the connection is closed and this 'Connection timed out' error is returned.","triggerScenarios":"zk.Connect succeeds at the TCP level but no StateHasSession event arrives within config.ConnectionTimeoutMS; or the zk event channel closes prematurely while the for/select loop is still waiting. Raised from openClient in agents/drivers/zookeeper/connection.go:213.","commonSituations":"ZooKeeper ensemble unreachable or overloaded (server up but slow to grant sessions); network firewall dropping packets silently (SYN succeeds, session handshake stalls); connection timeout configured too low for a distant/lossy network; DNS resolving to an unresponsive host.","solutions":["Verify the ZooKeeper ensemble is reachable and healthy (zkServer.sh status / ruok four-letter word on each host).","Increase the connectionTimeout config value (ConnectionTimeoutMS) so slow-but-working ensembles have time to grant a session.","Check network paths/firewalls between the client and the listed servers; silent packet drops stall the session handshake.","Confirm the connect string lists valid host:port entries and try connecting manually (e.g. nc host 2181)."],"exampleFix":"// before\nconnCfg.ConnectionTimeoutMS = 2000\n// after\nconnCfg.ConnectionTimeoutMS = 15000","handlingStrategy":"retry","validationCode":"// Pre-flight reachability check before connecting\nconn, err := net.DialTimeout(\"tcp\", host+\":2181\", 5*time.Second)\nif err != nil {\n    return fmt.Errorf(\"zookeeper host %s unreachable: %w\", host, err)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"var session *ClientSession\nerr := retry.Do(3, 2*time.Second, func() error {\n    s, err := openClient(cfg)\n    if err != nil {\n        if strings.Contains(err.Error(), \"Connection timed out\") {\n            return retry.Retryable(err) // transient network issue\n        }\n        return err // non-retryable\n    }\n    session = s\n    return nil\n})","preventionTips":["Set a generous ConnectionTimeoutMS (10-30s) for remote or lossy networks","Health-check the ensemble (ruok/stat four-letter words) before opening clients","Ensure the connect string lists multiple servers for failover","Monitor network path stability between app and ZooKeeper hosts"],"tags":["network","timeout","zookeeper","connection"],"backgroundTag":"connection-timeout","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"}