apache/iceberg · error · RuntimeException

Failed to check Zookeeper lock status

Error message

Failed to check Zookeeper lock status

What it means

The lock wrapper's isHeld() compares the VersionedValue<Integer> fetched from the SharedCount to LOCKED. getValue() may throw (node missing, connection issues, deserialization) and any such Exception is rethrown as RuntimeException "Failed to check Zookeeper lock status", so lock-state inspection failed rather than returning false.

Source

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

        }

        return acquired;
      } catch (Exception e) {
        LOG.warn("Failed to acquire Zookeeper lock", e);
        return false;
      }
    }

    @Override
    public boolean isHeld() {
      return isHeld(sharedCount.getVersionedValue());
    }

    private static boolean isHeld(VersionedValue<Integer> versionedValue) {
      try {
        return versionedValue.getValue() == LOCKED;
      } catch (Exception e) {
        throw new RuntimeException("Failed to check Zookeeper lock status", e);
      }
    }

    @Override
    public void unlock() {
      try {
        sharedCount.setCount(UNLOCKED);
        LOG.debug("Released lock for path: {}", lockPath);
      } catch (Exception e) {
        LOG.warn("Failed to release lock for path: {}", lockPath, e);
        throw new RuntimeException("Failed to release lock", e);
      }
    }
  }

  @VisibleForTesting
  RetryPolicy createRetryPolicy() {
    ZKRetryPolicies effectivePolicy =

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the wrapped cause for KeeperException (SessionExpired/NoNode/ConnectionLoss)
2. Ensure ZooKeeper connectivity is stable; increase session timeout if sessions expire mid-cycle
3. Recreate the lock factory (open()) after a session loss — the SharedCount must be restarted
4. Prevent external tooling from deleting lock znodes under the base path

Example fix

// before
if (!lockFactory.isHeld()) { ... } // RuntimeException on ZK failure
// after
try {
  if (!lockFactory.isHeld()) { ... }
} catch (RuntimeException e) {
  throw new IOException("ZK lock state unavailable, aborting maintenance", e);
}

// preflight health check
client.checkExists().forPath(lockPath); // ensure znode exists and session is fresh

try { boolean held = factory.isHeld(); } catch (RuntimeException e) { /* reconnect / reopen factory before retrying */ }

When it happens

Trigger: tryLock() or isHeld() invoked when the SharedCount value cannot be read: ZooKeeper session expired, shared-count node deleted externally, or connection failure during get().

Common situations: ZooKeeper session loss during long maintenance cycles; another process deleted the lock znode; network blip while checking lock state before committing maintenance.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed to check Zookeeper lock status
• Failed to check Zookeeper lock status
• Failed to release lock
• Failed to release lock for path: {}
• Connection to Zookeeper timed out

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