{"record":{"id":"941fbb1630a9c889","repo":"apache/iceberg","slug":"connection-to-zookeeper-timed-out-941fbb","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.1/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.1/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/ZkLockFactory.java#L108-L144","documentation":"Thrown by ZkLockFactory.open() when the Curator client cannot reach Zookeeper within the configured connectionTimeoutMs; blockUntilConnected returns false and the factory refuses to start. It guards the maintenance-table lock infrastructure (SharedCount-based) against operating without a live session.","triggerScenarios":"ZkLockFactoryBuilder.build()/open() called while the Zookeeper quorum is unreachable, DNS fails, the connect string is wrong, TLS/auth is misconfigured, or the network is slow enough that connectionTimeoutMs elapses before the session is established.","commonSituations":"Zookeeper cluster down or being restarted; wrong connectString (host/port) in table lock properties; firewall or security group blocking the client port; Zookeeper under load causing slow session establishment; container startup ordering (Flink job starts before Zookeeper is ready).","solutions":["Verify the Zookeeper connect string and that the quorum is reachable from the Flink job (telnet/nc host:2181)","Increase the connection timeout in the lock configuration (e.g. lock.client.connection-timeout-ms) and retry the job","Check Zookeeper server logs and cluster health (zookeeper quorum, SASL/TLS settings)","Ensure Flink TaskManagers have network/DNS access to the Zookeeper ensemble"],"exampleFix":"// before\nTableMaintenance.locks(ZookeeperLockFactory.builder()\n    .withZkAddress(\"zk-1:2181\")\n    .withConnectionTimeout(5000))\n// after\nTableMaintenance.locks(ZookeeperLockFactory.builder()\n    .withZkAddress(\"zk-1:2181,zk-2:2181,zk-3:2181\")\n    .withConnectionTimeout(60000))","handlingStrategy":"retry","validationCode":"// before opening the lock factory\ntry (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(zkHost, zkPort), 5000); // throws if unreachable\n}","typeGuard":null,"tryCatchPattern":"// ZookeeperLockFactory / ZkLockFactory.open\ntry {\n  lockFactory.open();\n} catch (RuntimeException e) {\n  if (e.getMessage().contains(\"Connection to Zookeeper timed out\")) {\n    // backoff and retry open, or fail the task with a clear message\n  } else { throw e; }\n}","preventionTips":["Use a multi-host Zookeeper connect string","Set a generous connection timeout (>= 30s) for cloud environments","Add readiness checks ensuring Zookeeper is up before Flink jobs start","Monitor Zookeeper quorum health and client session metrics"],"tags":["zookeeper","network","timeout","flink"],"backgroundTag":"request-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"}