apache/iceberg · error · RuntimeException

Failed to release lock

Error message

Failed to release lock

What it means

ZkLock.unlock() sets the SharedCount back to UNLOCKED. If that ZooKeeper write fails, the failure is logged as a warning with the path and rethrown as RuntimeException "Failed to release lock". The lock row/counter may remain LOCKED, blocking subsequent maintenance cycles until released or expired.

Source

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

      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 =
        (retryPolicy == null) ? ZKRetryPolicies.EXPONENTIAL_BACKOFF : retryPolicy;

    switch (effectivePolicy) {
      case ONE_TIME:
        return new RetryOneTime(baseSleepTimeMs);

      case N_TIME:
        return new RetryNTimes(maxRetries, baseSleepTimeMs);

      case BOUNDED_EXPONENTIAL_BACKOFF:
        return new BoundedExponentialBackoffRetry(baseSleepTimeMs, maxSleepTimeMs, maxRetries);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the wrapped cause (KeeperException) for connection/auth/version issues
2. Retry the unlock or restart the job so a fresh lock factory reconnects and clears the counter
3. Manually reset the shared-count znode to the unlocked value if the lock is stuck
4. Increase session timeout / retry policy so short ZK hiccups do not break unlock

Example fix

// before
lock.unlock(); // RuntimeException: Failed to release lock
// after
try {
  lock.unlock();
} catch (RuntimeException e) {
  LOG.warn("Unlock failed, will reset lock znode", e); // remediate stale LOCKED state
}

// preflight: confirm write ACL and session freshness
client.checkExists().forPath(lockPath);

try { lock.unlock(); } catch (RuntimeException e) { /* retry unlock; if still stuck reset the shared-count znode to UNLOCKED */ }

When it happens

Trigger: Calling unlock() on the ZK-based TriggerLockFactory lock when sharedCount.setCount(UNLOCKED) fails due to connection loss, session expiry, version conflict, or no permission.

Common situations: ZooKeeper ensemble briefly unreachable at commit time; session expired during a long maintenance run; ACL denies write on the lock node; stale version of the shared counter.

Related errors

• Failed to release lock
• Interrupted during unlock
• Failed to remove lock %s
• Failed to check Zookeeper lock status
• Failed to release lock for path: {}

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