{"record":{"id":"98529de08d3bf112","repo":"apache/iceberg","slug":"failed-to-heartbeat-for-hive-lock-s","errorCode":null,"errorMessage":"Failed to heartbeat for hive lock. %s","messagePattern":"Failed to heartbeat for hive lock\\. (.+?)","errorType":"exception","errorClass":"LockException","httpStatus":null,"severity":"error","filePath":"hive-metastore/src/main/java/org/apache/iceberg/hive/MetastoreLock.java","lineNumber":160,"sourceCode":"    // from the same JVM process, which would result in unnecessary HMS lock acquisition requests\n    acquireJvmLock();\n\n    // Getting HMS lock\n    hmsLockId = Optional.of(acquireLock());\n\n    // Starting heartbeat for the HMS lock\n    heartbeat = new Heartbeat(metaClients, hmsLockId.get(), lockHeartbeatIntervalTime);\n    heartbeat.schedule(exitingScheduledExecutorService);\n  }\n\n  @Override\n  public void ensureActive() throws LockException {\n    if (heartbeat == null) {\n      throw new LockException(\"Lock is not active\");\n    }\n\n    if (heartbeat.encounteredException != null) {\n      throw new LockException(\n          heartbeat.encounteredException,\n          \"Failed to heartbeat for hive lock. %s\",\n          heartbeat.encounteredException.getMessage());\n    }\n    if (!heartbeat.active()) {\n      throw new LockException(\"Hive lock heartbeat thread not active\");\n    }\n  }\n\n  @Override\n  public void unlock() {\n    if (heartbeat != null) {\n      heartbeat.cancel();\n      exitingScheduledExecutorService.shutdown();\n    }\n\n    try {\n      unlock(hmsLockId);","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/hive-metastore/src/main/java/org/apache/iceberg/hive/MetastoreLock.java#L142-L178","documentation":"The lock's heartbeat thread hit an exception while heartbeating the Hive lock to the metastore, so the lock can no longer be considered valid. ensureActive surfaces this as a LockException so the commit is aborted rather than proceeding with a possibly-lost lock.","triggerScenarios":"Heartbeat thread's metastore heartbeatLock call threw (TException, connection loss, lock already expired/released); ensureActive reads heartbeat.encounteredException and rethrows it.","commonSituations":"Long commits exceeding lock timeout so the metastore reaped the lock; metastore outage during commit; heartbeat interval longer than metastore's lock timeout (hive.txn.timeout).","solutions":["Retry the commit; the lock must be re-acquired after the heartbeat failure.","Increase hive.txn.timeout or ensure heartbeats fire well within it for long-running commits.","Check metastore availability/network stability during the commit window."],"exampleFix":"// before\nconf: lock-heartbeat-interval = 1h (longer than metastore lock timeout)\n\n// after\nconf: heartbeat interval set well below hive.txn.timeout (e.g. minutes),\nretry commit on CommitFailedException","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  commit();\n} catch (CommitFailedException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Failed to heartbeat\")) {\n    // re-acquire lock, refresh view, retry with backoff\n  }\n}","preventionTips":["Set heartbeat interval well below hive.txn.timeout.","Monitor metastore connectivity for the duration of long commits.","Keep commits short; split very large operations."],"tags":["hive","locking","heartbeat","metastore"],"backgroundTag":"request-timeout","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}