apache/iceberg · error · LockException

Timed out after %s ms waiting for lock on %s.%s

Error message

Timed out after %s ms waiting for lock on %s.%s

What it means

The lock acquisition loop gave up after the configured timeout without reaching ACQUIRED state. Iceberg throws LockException with the waited duration and table coordinates, and the commit is abandoned (it will surface as a CommitFailedException upstream).

Source

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

                        e);
                  }
                },
                TException.class);
      }
    } 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;
    }
  }

  /**

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Increase the lock acquisition timeout in the Hive catalog/lock configuration.
2. Identify and resolve the competing lock holder (SHOW LOCKS, Hive transaction list, kill stale transactions).
3. Reduce concurrent writers or stagger job schedules to avoid overlap.
4. Retry the commit once the lock is available.

Example fix

// before
CatalogUtil lock config: lock acquisition timeout = 1000ms (too low)

// after
set hive catalog lock acquisition/heartbeat timeouts to allow
realistic waits, e.g. several minutes, then retry commit on failure

try {
  commit();
} catch (CommitFailedException e) {
  if (e.getMessage() != null && e.getMessage().contains("Timed out")) {
    // verify lock holder gone, then re-acquire and retry with backoff
  }
}

When it happens

Trigger: acquireLock ran its full retry window with checkLock repeatedly returning WAITING (or not ACQUIRED) and timeout=true; called from lock() during doCommit under heavy contention or a stuck competing transaction.

Common situations: Long-running or hung Hive transaction blocking the table; many concurrent writers; lock timeout configured too low for legitimate contention.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Waiting for lock on table %s.%s
• Failed to find lock for table %s.%s
• Failed to acquire locks from metastore because the underlyin
• Lock is not active
• Failed to heartbeat for hive lock. %s

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