apache/iceberg · error · LockException

Metastore operation failed for %s.%s

Error message

Metastore operation failed for %s.%s

What it means

The lock acquisition loop ended in a non-ACQUIRED state but neither the timeout nor a recorded thrift error explains it, so this safety-net LockException is thrown. It indicates an unmet invariant in the locking protocol (lockId null, unexpected state, or lost bookkeeping).

Source

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

    } catch (WaitingForLockException e) {
      timeout = true;
      duration = System.currentTimeMillis() - start;
    } catch (TException e) {
      thriftError = e;
    } finally {
      if (!lockInfo.lockState.equals(LockState.ACQUIRED)) {
        unlock(Optional.of(lockInfo.lockId));
      }
    }

    if (!lockInfo.lockState.equals(LockState.ACQUIRED)) {
      if (timeout) {
        throw new LockException(
            "Timed out after %s ms waiting for lock on %s.%s", duration, databaseName, tableName);
      }

      if (thriftError != null) {
        throw new LockException(
            thriftError, "Metastore operation failed for %s.%s", databaseName, tableName);
      }

      // Just for safety. We should not get here.
      throw new LockException(
          "Could not acquire the lock on %s.%s, lock request ended in state %s",
          databaseName, tableName, lockInfo.lockState);
    } else {
      return lockInfo.lockId;
    }
  }

  /**
   * Creates a lock, retrying if possible on failure.
   *
   * @return The {@link LockInfo} object for the successfully created lock
   * @throws LockException When we are not able to fill the hostname for lock creation, or there is
   *     an error during lock creation

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the commit — this is treated as a lock acquisition failure and the commit should be re-attempted.
2. Inspect the metastore lock table (SHOW LOCKS / HIVE_LOCKS rows) for the stuck or aborted lock.
3. Upgrade the iceberg-hive-metastore/Hive versions if the metastore exhibits known lock-state bugs.
4. Report persistent occurrences with the lock state details; this path indicates an invariant violation.

try {
  commit();
} catch (CommitFailedException e) {
  if (e.getMessage() != null && e.getMessage().contains("Could not acquire the lock")) {
    // unexpected lock state: re-acquire lock and retry; escalate if persistent
  }
}

When it happens

Trigger: acquireLock exits the loop with lockState != ACQUIRED, timeout=false and thriftError=null — e.g. checkLock returned an unexpected state transition path or the lockId acquisition path skipped state updates.

Common situations: Metastore returning unexpected lock states (ABORTED/error paths not classified); races between lock creation and checkLock; Hive metastore version quirks in lock semantics.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Failed to acquire locks from metastore because the underlyin
• Failed to heartbeat for hive lock. %s
• Could not acquire the lock on %s.%s, lock request ended in s
• Interrupted finding locks to unlock {}.{}
• Failed to list all tables under namespace ${namespace}

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