apache/iceberg · warning

Failed to unlock {}.{}

Error message

Failed to unlock {}.{}

What it means

MetastoreLock.unlock catches any Exception from the unlock flow (lock lookup or doUnlock) and logs this warning with database and table names, then returns. The lock may remain in HMS; unlock never throws to the caller.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/MetastoreLock.java:426

      doUnlock(id);
    } catch (InterruptedException ie) {
      if (id != null) {
        // Interrupted unlock. We try to unlock one more time if we have a lockId
        try {
          Thread.interrupted(); // Clear the interrupt status flag for now, so we can retry unlock
          LOG.warn("Interrupted unlock we try one more time {}.{}", databaseName, tableName, ie);
          doUnlock(id);
        } catch (Exception e) {
          LOG.warn("Failed to unlock even on 2nd attempt {}.{}", databaseName, tableName, e);
        } finally {
          Thread.currentThread().interrupt(); // Set back the interrupt status
        }
      } else {
        Thread.currentThread().interrupt(); // Set back the interrupt status
        LOG.warn("Interrupted finding locks to unlock {}.{}", databaseName, tableName, ie);
      }
    } catch (Exception e) {
      LOG.warn("Failed to unlock {}.{}", databaseName, tableName, e);
    }
  }

  private void doUnlock(long lockId) throws TException, InterruptedException {
    metaClients.run(
        client -> {
          client.unlock(lockId);
          return null;
        });
  }

  private void acquireJvmLock() {
    if (jvmLock != null) {
      throw new IllegalStateException(
          String.format("Cannot call acquireLock twice for %s", fullName));
    }

    jvmLock = commitLockCache.get(fullName, t -> new ReentrantLock(true));

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify HMS availability and inspect metastore server logs for unlock failures
2. Check for leftover locks with SHOW LOCKS and clear them if orphaned
3. Retry the commit/operation; ensure lock lifecycle is wrapped in try/finally so unlock always runs
4. Increase client timeouts if metastore is slow

Example fix

// before
lock.unlock(); // exception swallowed silently
// after
lock.unlock();
Tasks.foreach(() -> hiveClient.unlock(lockId)) // verify cleanup externally if needed
    .retry(3).suppressExceptions();

try { lock.close(); } catch (Exception e) { /* log and verify HMS lock state manually */ }

When it happens

Trigger: Any failure while releasing the Hive lock: HMS connection errors, TException from client.unlock, lookup failures by lockId or agentInfo.

Common situations: HMS outages during commit finalization; stale/invalid lock ids after metastore restarts; interrupted threads hitting generic exceptions.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Could not find lock with HMSClient {}
• Failed to create lock {}
• Failed to release lock
• Interrupted during unlock
• Failed to remove lock %s

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