apache/iceberg · error · RuntimeException

Metastore operation failed for %s.%s

Error message

Metastore operation failed for %s.%s

What it means

Any Thrift exception (TException) propagating out of the HMS persistTable call — and not matching the more specific handlers — is wrapped in a RuntimeException 'Metastore operation failed for <db>.<table>'. It signals the HMS RPC itself failed (connection problem, protocol mismatch, server error) without a more precise classification.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveTableOperations.java:415

          LOG.error(
              "Cannot tell if commit to {}.{} succeeded, attempting to reconnect and check.",
              database,
              tableName,
              e);
          commitStatus = checkCommitStatus(newMetadataLocation, tableMetadata);
        }

        switch (commitStatus) {
          case SUCCESS:
            break;
          case FAILURE:
            throw e;
          case UNKNOWN:
            throw new CommitStateUnknownException(e);
        }
      }
    } catch (TException e) {
      throw new RuntimeException(
          String.format("Metastore operation failed for %s.%s", database, tableName), e);

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new RuntimeException("Interrupted during commit", e);

    } catch (LockException e) {
      throw new CommitFailedException(e);

    } finally {
      HiveOperationsBase.cleanupMetadataAndUnlock(io(), commitStatus, newMetadataLocation, lock);
    }

    LOG.info(
        "Committed to table {} with the new metadata location {}", fullName, newMetadataLocation);
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check HMS availability and connectivity (hive.metastore.uris, network, metastore logs)
2. Fix the underlying TException cause — inspect the wrapped cause chain
3. Retry the commit; if state is unknown, verify metadata_location in HMS first
4. Align client/server Thrift and Hive versions

Example fix

// before
conf.set("hive.metastore.uris", ""); // local embedded, may lack txn/lock support
// after
conf.set("hive.metastore.uris", "thrift://hms-host:9083");
conf.set("hive.metastore.client.connect.retry.attempts", "5");

// pre-check HMS reachability
HiveConf hc = new HiveConf();
new MetaStoreClientFactory(). // or a lightweight thrift ping to hive.metastore.uris before committing

try {
  table.newAppend().appendFile(f).commit();
} catch (RuntimeException e) {
  if (e.getCause() instanceof TException) {
    // check HMS state: metadata_location may or may not have advanced
    verifyCommitStateThenRetry();
  } else throw e;
}

When it happens

Trigger: doCommit calling persistTable/alterTable when the metastore client throws TException: HMS unreachable, connection closed mid-call, Thrift protocol/version mismatch, or generic server-side MetaException.

Common situations: HMS down or restarted during commit; network partition between client and metastore; incompatible hive-metastore client vs server versions; metastore timeouts.

Related errors

• Failed to list all views under namespace ${namespace}
• Failed to drop ${identifier}
• Failed to drop view ${identifier}
• Failed to check table existence of ${baseTableIdentifier}
• Failed to check view existence of ${viewIdentifier}

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