{"record":{"id":"d6da3b6aaf89fb4b","repo":"apache/iceberg","slug":"failed-to-acquire-locks-from-metastore-because-the","errorCode":null,"errorMessage":"Failed to acquire locks from metastore because the underlying metastore table 'HIVE_LOCKS' does not exist. This can occur when using an embedded metastore which does not support transactions. To fix this use an alternative metastore.","messagePattern":"Failed to acquire locks from metastore because the underlying metastore table 'HIVE_LOCKS' does not exist\\. This can occur when using an embedded metastore which does not support transactions\\. To fix this use an alternative metastore\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hive-metastore/src/main/java/org/apache/iceberg/hive/HiveTableOperations.java","lineNumber":373,"sourceCode":"        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, \"Table already exists: %s.%s\", database, tableName);\n\n      } catch (InvalidObjectException e) {\n        throw new ValidationException(e, \"Invalid Hive object for %s.%s\", database, tableName);\n\n      } catch (CommitFailedException | CommitStateUnknownException e) {\n        throw e;\n\n      } catch (Throwable e) {\n        if (e.getMessage() != null\n            && e.getMessage().contains(\"Table/View 'HIVE_LOCKS' does not exist\")) {\n          throw new RuntimeException(\n              \"Failed to acquire locks from metastore because the underlying metastore \"\n                  + \"table 'HIVE_LOCKS' does not exist. This can occur when using an embedded metastore which does not \"\n                  + \"support transactions. To fix this use an alternative metastore.\",\n              e);\n        }\n\n        commitStatus = BaseMetastoreOperations.CommitStatus.UNKNOWN;\n        if (e.getMessage() != null\n            && e.getMessage()\n                .contains(\n                    \"The table has been modified. The parameter value for key '\"\n                        + HiveTableOperations.METADATA_LOCATION_PROP\n                        + \"' is\")) {\n          // It's possible the HMS client incorrectly retries a successful operation, due to network\n          // issue for example, and triggers this exception. So we need double-check to make sure\n          // this is really a concurrent modification. Hitting this exception means no pending\n          // requests, if any, can succeed later, so it's safe to check status in strict mode\n          commitStatus = checkCommitStatusStrict(newMetadataLocation, tableMetadata);","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/hive-metastore/src/main/java/org/apache/iceberg/hive/HiveTableOperations.java#L355-L391","documentation":"When using Hive's in-process lock manager, locking data is stored in a transactional 'HIVE_LOCKS' table in the metastore's backing database. If that table does not exist (typical with an embedded metastore, e.g. Derby in non-transactional mode), lock acquisition fails inside doCommit and this RuntimeException is thrown, telling the user to switch metastores.","triggerScenarios":"doCommit with Hive locking enabled (hive.metadata lock enabled / iceberg.hive.lock.enabled) where the lock manager hits 'Table/View HIVE_LOCKS does not exist' — i.e. the HMS backing DB lacks the transaction tables needed by the in-process lock manager.","commonSituations":"Local/dev setups using the embedded Derby metastore; misconfigured metastore that doesn't run schematool transaction initialization; test environments without a real HMS database.","solutions":["Use a real external metastore (remote HMS service backed by MySQL/Postgres) instead of the embedded one","Disable Hive locking if you don't need it: set iceberg.hive.lock.enabled=false (lockHeartbeat/lock Enabled false path)","Initialize the metastore schema properly (schematool -initSchema) and enable transaction support (hive.txn.manager=DbTxnManager, hive.compactor.initiator.on etc.)","For tests, configure the embedded metastore to support the lock tables or disable locking"],"exampleFix":"// before\nconf.set(\"iceberg.hive.lock.enabled\", \"true\"); // with embedded Derby metastore\n// after\nconf.set(\"iceberg.hive.lock.enabled\", \"false\");\n// or point to a real metastore:\nconf.set(\"hive.metastore.uris\", \"thrift://metastore-host:9083\");","handlingStrategy":"fallback","validationCode":"// guard config\nboolean embedded = conf.get(\"hive.metastore.uris\", \"\").isEmpty();\nboolean lockEnabled = conf.getBoolean(\"iceberg.hive.lock.enabled\", false);\nif (embedded && lockEnabled) throw new IllegalArgumentException(\"Hive locks require a non-embedded metastore\");","typeGuard":null,"tryCatchPattern":"try {\n  table.newAppend().appendFile(f).commit();\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"HIVE_LOCKS\")) {\n    conf.set(\"iceberg.hive.lock.enabled\", \"false\"); // fallback: disable locking\n    // or reconfigure to a remote metastore\n  } else throw e;\n}","preventionTips":["Never use the embedded metastore with Hive locking enabled in production","Run schematool and enable DbTxnManager when locking is required","Point hive.metastore.uris at a real HMS service","Disable iceberg.hive.lock.enabled if you don't need Hive-side locking"],"tags":["hive-metastore","locking","embedded-metastore","configuration"],"backgroundTag":"missing-dependency","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"}