apache/iceberg · error · RuntimeException

Failed to initialize SharedCount

Error message

Failed to initialize SharedCount

What it means

After connecting, ZkLockFactory.open() creates and starts two SharedCount instances (task and recovery counters). Any exception starting them is wrapped in RuntimeException("Failed to initialize SharedCount") and the client is closed quietly first. This means the ZK connection succeeded but the distributed counters used by the trigger lock could not be set up.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/maintenance/api/ZkLockFactory.java:140

    client.start();

    try {
      if (!client.blockUntilConnected(connectionTimeoutMs, TimeUnit.MILLISECONDS)) {
        throw new IllegalStateException("Connection to Zookeeper timed out");
      }

      this.taskSharedCount = new SharedCount(client, getTaskSharePath(), 0);
      this.recoverySharedCount = new SharedCount(client, getRecoverySharedPath(), 0);
      taskSharedCount.start();
      recoverySharedCount.start();
      isOpen = true;
      LOG.info("ZkLockFactory initialized for lockId: {}.", lockId);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new RuntimeException("Interrupted while connecting to Zookeeper", e);
    } catch (Exception e) {
      closeQuietly();
      throw new RuntimeException("Failed to initialize SharedCount", e);
    }
  }

  private String getTaskSharePath() {
    return LOCK_BASE_PATH + lockId + "/task";
  }

  private String getRecoverySharedPath() {
    return LOCK_BASE_PATH + lockId + "/recovery";
  }

  private void closeQuietly() {
    try {
      close();
    } catch (Exception e) {
      LOG.warn("Failed to close ZkLockFactory for lockId: {}", lockId, e);
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Read the wrapped cause: fix the Curator/ZK error it reports (connection loss, bad ACLs, bad arguments).
2. Verify the configured lockId yields a valid znode path (no special characters) and that LOCK_BASE_PATH is creatable/writable under your ACLs.
3. Check ZooKeeper server logs for session/ACL errors at the time of the failure.
4. Increase session/timeout settings and ensure the ensemble is stable before starting the job.
5. Retry open(); closeQuietly has released the client, so a fresh open attempt is safe.

Example fix

// before
ZkLockFactory.factory("zk:2181").withLockId("my/trigger:v1"); // '/' makes an invalid nested path
// after
ZkLockFactory.factory("zk:2181").withLockId("my-trigger-v1");

// validate lockId forms a safe znode path
if (!lockId.matches("[A-Za-z0-9._-]+")) throw new IllegalArgumentException("Invalid lockId: " + lockId);

try { lockFactory.open(); } catch (RuntimeException e) { if (e.getMessage().contains("Failed to initialize SharedCount")) { log.error("SharedCount init failed: {}", e.getCause(), e); } throw e; }

When it happens

Trigger: open() calls taskSharedCount.start()/recoverySharedCount.start() and Curator throws: connection dropped right after startup, ZK authorization/acl failure, invalid node path, or session expiry.

Common situations: ZooKeeper ensemble restarted between connect and counter start; chroot or ACL configuration denying writes to LOCK_BASE_PATH; invalid lockId producing an illegal znode path (bad characters); very short session timeout.

Related errors

• Failed to initialize SharedCount
• Connection to Zookeeper timed out
• Failed to check Zookeeper lock status
• Failed to check Zookeeper lock status
• Interrupted while connecting to Zookeeper

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/1a62301ebaa46b9f. Report an issue: GitHub.