apache/iceberg · critical · RuntimeException

Failed to acquire locks from metastore because the underlyin

Error message

Failed to acquire locks from metastore because the underlying metastore view '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.

What it means

The Hive metastore lacks the HIVE_LOCKS table, which Iceberg's locking relies on for transactional lock management. This is typical of an embedded/DERBY metastore or misconfigured metastore that does not support the transactional locking schema. Iceberg throws a RuntimeException wrapping the original Thrift exception.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveViewOperations.java:224

        throw new ValidationException(e, "Invalid Hive object for %s.%s", database, viewName);

      } catch (CommitFailedException | CommitStateUnknownException e) {
        throw e;

      } catch (Throwable e) {
        if (e.getMessage() != null
            && e.getMessage()
                .contains(
                    "The table has been modified. The parameter value for key '"
                        + BaseMetastoreTableOperations.METADATA_LOCATION_PROP
                        + "' is")) {
          throw new CommitFailedException(
              e, "The view %s.%s has been modified concurrently", database, viewName);
        }

        if (e.getMessage() != null
            && e.getMessage().contains("Table/View 'HIVE_LOCKS' does not exist")) {
          throw new RuntimeException(
              "Failed to acquire locks from metastore because the underlying metastore "
                  + "view '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.",
              e);
        }

        LOG.error(
            "Cannot tell if commit to {}.{} succeeded, attempting to reconnect and check.",
            database,
            viewName,
            e);
        commitStatus = BaseMetastoreOperations.CommitStatus.UNKNOWN;
        commitStatus =
            checkCommitStatus(
                viewName,
                newMetadataLocation,
                metadata.properties(),
                () -> checkCurrentMetadataLocation(newMetadataLocation));

View on GitHub (pinned to 86d9c8fc54)

Solutions

Switch to a real external metastore (e.g. backed by MySQL/PostgreSQL) with a properly initialized schema (schematool).
Run schematool -initSchema against the metastore DB so the transactional lock tables exist.
For test setups, disable Hive locking and rely on a different concurrency mechanism if the metastore cannot support it.

Example fix

// before (hive-site.xml)
hive.metastore.uris = ""   // embedded Derby

// after
<property><name>hive.metastore.uris</name><value>thrift://metastore-host:9083</value></property>
<!-- metastore DB initialized via schematool -->

Defensive patterns

Strategy: validation

Validate before calling

// run schematool against the metastore DB before starting jobs, or verify lock tables exist:
// mysql> SHOW TABLES LIKE 'HIVE_LOCKS';
// also confirm hive.metastore.uris points at a real metastore, not embedded Derby

Prevention

Never use the embedded Derby metastore for concurrent Iceberg writes.
Initialize the metastore schema with schematool -initSchema before use.
Point hive.metastore.uris at an external metastore backed by MySQL/PostgreSQL.

When it happens

Trigger: Any commit that needs to acquire a Hive lock while the metastore database does not contain the HIVE_LOCKS table; checkLock/acquireLock Thrift calls fail with "Table/View 'HIVE_LOCKS' does not exist".

Common situations: Using hive.metastore.warehouse with embedded Derby metastore in dev/test; a metastore initialized without transaction support; corrupted or wiped metastore schema.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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