{"record":{"id":"a4a5782495446ae5","repo":"apache/iceberg","slug":"failed-to-heartbeat-for-hive-lock-while-committing-a4a578","errorCode":null,"errorMessage":"Failed to heartbeat for hive lock while committing changes. This can lead to a concurrent commit attempt be able to overwrite this commit. Please check the commit history. If you are running into this issue, try reducing iceberg.hive.lock-heartbeat-interval-ms.","messagePattern":"Failed to heartbeat for hive lock while committing changes\\. This can lead to a concurrent commit attempt be able to overwrite this commit\\. Please check the commit history\\. If you are running into this issue, try reducing iceberg\\.hive\\.lock-heartbeat-interval-ms\\.","errorType":"exception","errorClass":"CommitStateUnknownException","httpStatus":null,"severity":"critical","filePath":"hive-metastore/src/main/java/org/apache/iceberg/hive/HiveViewOperations.java","lineNumber":196,"sourceCode":"      }\n      HMSTablePropertyHelper.updateHmsTableForIcebergView(\n          newMetadataLocation,\n          tbl,\n          metadata,\n          removedProps,\n          maxHiveTablePropertySize,\n          currentMetadataLocation(),\n          sqlFor(metadata));\n      lock.ensureActive();\n\n      try {\n        persistTable(tbl, updateHiveView, hiveLockEnabled(conf) ? null : baseMetadataLocation);\n        lock.ensureActive();\n\n        commitStatus = CommitStatus.SUCCESS;\n      } catch (LockException le) {\n        commitStatus = CommitStatus.UNKNOWN;\n        throw new CommitStateUnknownException(\n            \"Failed to heartbeat for hive lock while \"\n                + \"committing changes. This can lead to a concurrent commit attempt be able to overwrite this commit. \"\n                + \"Please check the commit history. If you are running into this issue, try reducing \"\n                + \"iceberg.hive.lock-heartbeat-interval-ms.\",\n            le);\n      } catch (org.apache.hadoop.hive.metastore.api.AlreadyExistsException e) {\n        throw new AlreadyExistsException(e, \"View already exists: %s.%s\", database, viewName);\n\n      } catch (InvalidObjectException e) {\n        throw new ValidationException(e, \"Invalid Hive object for %s.%s\", database, viewName);\n\n      } catch (CommitFailedException | CommitStateUnknownException e) {\n        throw e;\n\n      } catch (Throwable e) {\n        if (e.getMessage() != null\n            && e.getMessage()\n                .contains(","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/hive-metastore/src/main/java/org/apache/iceberg/hive/HiveViewOperations.java#L178-L214","documentation":"After persisting the view, doCommit calls lock.ensureActive() to verify the Hive lock heartbeat is still alive. If the heartbeat failed (LockException), the commit's outcome is uncertain — another commit may overwrite it — so it throws CommitStateUnknownException with commitStatus UNKNOWN. Callers must check history rather than assume success or failure.","triggerScenarios":"Committing a Hive view while holding a Hive lock whose heartbeat fails — e.g., HMS unreachable during heartbeat, lock expired due to long commit, or heartbeat interval too large (iceberg.hive.lock-heartbeat-interval-ms too high).","commonSituations":"Long garbage-collection pauses or network interruptions during commit; HMS restarts mid-commit; lock expiry under slow metastore operations; misconfigured heartbeat interval.","solutions":["Inspect the view's commit history/metadata location to determine whether the commit landed before retrying — do NOT blindly re-commit.","Lower iceberg.hive.lock-heartbeat-interval-ms so heartbeats survive slow commits.","Check HMS connectivity and lock table state; re-run after the metastore is healthy.","Treat CommitStateUnknownException as non-retryable-automatically; reconcile state first (Iceberg will resolve to the last successful commit)."],"exampleFix":"// before\ntry { view.replaceView(...).commit(); } catch (CommitStateUnknownException e) { retry(); }\n// after\ncatch (CommitStateUnknownException e) {\n  View current = views.loadView(identifier); // check which commit actually won\n  // reconcile with current state before any retry\n}","handlingStrategy":"try-catch","validationCode":"// Keep heartbeat interval safely below expected commit duration\nString interval = conf.get(\"iceberg.hive.lock-heartbeat-interval-ms\");\n// e.g., ensure interval < (expected commit time / 3)\n","typeGuard":null,"tryCatchPattern":"try {\n  view.replaceView(...).commit();\n} catch (CommitStateUnknownException e) {\n  // DO NOT auto-retry; inspect current metadata/history to learn if commit landed\n  View current = views.loadView(identifier);\n  // reconcile against current state\n}","preventionTips":["Set iceberg.hive.lock-heartbeat-interval-ms low enough for slow commits.","Avoid long GC pauses during commit; size executors appropriately.","Ensure stable HMS connectivity for the commit window.","Never assume failure after CommitStateUnknownException — always check history first."],"tags":["hive-metastore","lock","heartbeat","commit-state-unknown"],"backgroundTag":"invalid-state-transition","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}