{"record":{"id":"09eda428a6a74365","repo":"apache/iceberg","slug":"connection-to-zookeeper-timed-out-09eda4","errorCode":null,"errorMessage":"Connection to Zookeeper timed out","messagePattern":"Connection to Zookeeper timed out","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/ZkLockFactory.java","lineNumber":126,"sourceCode":"  @Override\n  public void open() {\n    if (isOpen) {\n      LOG.debug(\"ZkLockFactory already opened for lockId: {}.\", lockId);\n      return;\n    }\n\n    this.client =\n        CuratorFrameworkFactory.builder()\n            .connectString(connectString)\n            .sessionTimeoutMs(sessionTimeoutMs)\n            .connectionTimeoutMs(connectionTimeoutMs)\n            .retryPolicy(createRetryPolicy())\n            .build();\n    client.start();\n\n    try {\n      if (!client.blockUntilConnected(connectionTimeoutMs, TimeUnit.MILLISECONDS)) {\n        throw new IllegalStateException(\"Connection to Zookeeper timed out\");\n      }\n\n      this.taskSharedCount = new SharedCount(client, getTaskSharePath(), 0);\n      this.recoverySharedCount = new SharedCount(client, getRecoverySharedPath(), 0);\n      taskSharedCount.start();\n      recoverySharedCount.start();\n      isOpen = true;\n      LOG.info(\"ZkLockFactory initialized for lockId: {}.\", lockId);\n    } catch (InterruptedException e) {\n      Thread.currentThread().interrupt();\n      throw new RuntimeException(\"Interrupted while connecting to Zookeeper\", e);\n    } catch (Exception e) {\n      closeQuietly();\n      throw new RuntimeException(\"Failed to initialize SharedCount\", e);\n    }\n  }\n\n  private String getTaskSharePath() {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/ZkLockFactory.java#L108-L144","documentation":"ZkLockFactory.open() starts the Curator client and blocks until connected within connectionTimeoutMs. If the connection is not established in time, it throws IllegalStateException \"Connection to Zookeeper timed out\", meaning the table maintenance lock cannot be used without a working ZooKeeper.","triggerScenarios":"Creating a ZkLockFactory via TriggerLockFactory lock config where the ZooKeeper quorum is unreachable or slower than connectionTimeoutMs during open()/tryLock initialization.","commonSituations":"Wrong zookeeper connect string or port; ZooKeeper ensemble down or in a network partition; firewall/DNS blocking; connectionTimeoutMs too small for a slow cluster; auth/SASL handshake hanging.","solutions":["Verify the ZooKeeper connect string and that the ensemble is reachable (zkCli smoke test)","Increase the connection timeout configuration to cover slow cluster startup","Check firewall, DNS, and Kerberos/SASL settings between Flink and ZooKeeper","Ensure ZooKeeper quorum health (majority of servers up) before launching the job"],"exampleFix":"// before\nZkLockFactory.builder().setConnectString(\"zk1:2181\").setConnectionTimeoutMs(1000)...\n// after\nZkLockFactory.builder().setConnectString(\"zk1:2181,zk2:2181,zk3:2181\").setConnectionTimeoutMs(60000)...","handlingStrategy":"validation","validationCode":"// before opening the lock factory\nProcess p = Runtime.getRuntime().exec(\"echo ruok | nc zk1 2181\");\nboolean healthy = new String(p.getInputStream().readAllBytes()).trim().equals(\"imok\");","typeGuard":null,"tryCatchPattern":"try { factory.open(); } catch (IllegalStateException e) { /* retry with backoff or fail fast: ZK unreachable */ }","preventionTips":["Use a multi-host ZooKeeper connect string","Size connectionTimeoutMs above worst-case cluster connect time","Verify firewall/DNS/Kerberos between Flink and ZooKeeper","Monitor ZK quorum health before job startup"],"tags":["zookeeper","timeout","network","flink"],"backgroundTag":"connection-timeout","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}