apache/iceberg · error · LockException

Hive lock heartbeat thread not active

Error message

Hive lock heartbeat thread not active

What it means

The heartbeat thread exists but is no longer running (active() returned false), meaning the lock heartbeat stopped without recording an exception. The lock may have lapsed, so ensureActive fails to protect the commit.

Source

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

    // Starting heartbeat for the HMS lock
    heartbeat = new Heartbeat(metaClients, hmsLockId.get(), lockHeartbeatIntervalTime);
    heartbeat.schedule(exitingScheduledExecutorService);
  }

  @Override
  public void ensureActive() throws LockException {
    if (heartbeat == null) {
      throw new LockException("Lock is not active");
    }

    if (heartbeat.encounteredException != null) {
      throw new LockException(
          heartbeat.encounteredException,
          "Failed to heartbeat for hive lock. %s",
          heartbeat.encounteredException.getMessage());
    }
    if (!heartbeat.active()) {
      throw new LockException("Hive lock heartbeat thread not active");
    }
  }

  @Override
  public void unlock() {
    if (heartbeat != null) {
      heartbeat.cancel();
      exitingScheduledExecutorService.shutdown();
    }

    try {
      unlock(hmsLockId);
    } finally {
      releaseJvmLock();
    }
  }

  private long acquireLock() throws LockException {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the commit with a freshly acquired lock.
2. Verify the heartbeat executor is not shut down while the lock is held (check CloseableGroup/executor lifecycle).
3. Inspect thread dumps/logs to find why the scheduled heartbeat task stopped.

try {
  commit();
} catch (CommitFailedException e) {
  if (e.getMessage() != null && e.getMessage().contains("heartbeat thread not active")) {
    // re-acquire a fresh lock and retry
  }
}

When it happens

Trigger: Heartbeat scheduler thread died or was shut down (executor shutdown, unhandled error killing the scheduled task) while a lock was held; ensureActive called afterwards.

Common situations: JVM under extreme memory pressure killing threads; executor closed prematurely; custom subclass mismanaging the ScheduledExecutorService lifecycle.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Failed to heartbeat for hive lock. %s
• Interrupted while trying to find lock for table %s.%s
• Interrupted while creating lock on table %s.%s
• Failed to heartbeat for lock: %d
• Interrupted during tryLock

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