t8y2/dbx · error

connect to ZooKeeper: %w

Error message

connect to ZooKeeper: %w

What it means

This error wraps the ZooKeeper dialer failure in discovery.Endpoints (discovery.go:106). Before querying HiveServer2 endpoints from ZooKeeper, the driver connects to the ZooKeeper ensemble; if that connection cannot be established within the timeout, this error is returned with the underlying cause.

Source

Thrown at agents/drivers/hive-go/discovery.go:106

				dialer := &net.Dialer{Timeout: dialTimeout}
				return tls.DialWithDialer(dialer, network, address, config)
			}),
		)
	}
}

func (discovery *zooKeeperDiscovery) Endpoints(ctx context.Context, rejected map[string]bool) ([]endpoint, error) {
	addresses := make([]string, 0, len(discovery.servers))
	for _, server := range discovery.servers {
		addresses = append(addresses, server.address())
	}
	timeout := discovery.timeout
	if timeout <= 0 {
		timeout = defaultConnectTimeout
	}
	connection, events, err := discovery.dialer(addresses, timeout)
	if err != nil {
		return nil, fmt.Errorf("connect to ZooKeeper: %w", err)
	}
	defer connection.Close()
	if err := waitForZooKeeperSession(ctx, events, timeout); err != nil {
		return nil, err
	}
	if discovery.authScheme != "" || discovery.auth != "" {
		if discovery.authScheme == "" || discovery.auth == "" {
			return nil, errors.New("ZooKeeper auth scheme and credentials must be configured together")
		}
		if err := connection.AddAuth(discovery.authScheme, []byte(discovery.auth)); err != nil {
			return nil, fmt.Errorf("authenticate to ZooKeeper: %w", err)
		}
	}
	resolved := make([]endpoint, 0)
	var listedPath string
	var nodeFailures []string
	for _, path := range discovery.paths() {
		children, _, childrenErr := connection.Children(path)

View on GitHub (pinned to c0390bff16)

Solutions

1. Verify the ZooKeeper host:port list in the configuration is correct and resolvable.
2. Test network reachability to the zk quorum (telnet/nc host 2181).
3. Increase the ZooKeeper connect timeout if the ensemble is slow to respond.
4. Check ZooKeeper ensemble health (status via zkServer.sh status).

Example fix

// before
dsn := "hive://user:pass@host:10000/db?zookeeper=zk-internal:2181"
// after
dsn := "hive://user:pass@host:10000/db?zookeeper=zk1:2181,zk2:2181,zk3:2181&connectTimeout=30s"

for _, zk := range strings.Split(zkHosts, ",") {
    conn, err := net.DialTimeout("tcp", zk, 3*time.Second)
    if err != nil {
        return fmt.Errorf("zookeeper unreachable before connect: %s", zk)
    }
    conn.Close()
}

endpoints, err := discovery.Endpoints(ctx)
var zkErr error
if errors.As(err, &zkErr) || strings.Contains(err.Error(), "connect to ZooKeeper") {
    // check zk quorum reachability, then retry with backoff
    return retryWithBackoff(ctx, 3, func() error { _, err := discovery.Endpoints(ctx); return err })
}

When it happens

Trigger: discovery.dialer(addresses, timeout) fails: ZooKeeper hosts unreachable, wrong zk quorum addresses, DNS failure, or the connection exceeds the configured/default timeout.

Common situations: Wrong ZooKeeper host list in the connection string; zk port 2181 blocked by firewall; ZooKeeper ensemble down or in election; DNS name for zk hosts unresolvable from the client environment.

Related errors

• ZooKeeper connection timed out before a session was establis
• Connection timed out
• list ZooKeeper namespace %s: %w
• ZooKeeper connection event: %w
• ZooKeeper SASL round %d: %w

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