apache/iceberg · error · CommitFailedException

Cannot commit: Base metadata location '%s' is not same as th

Error message

Cannot commit: Base metadata location '%s' is not same as the current view metadata location '%s' for %s.%s

What it means

HiveViewOperations.doCommit performs Iceberg's optimistic concurrency check: the base metadata location recorded by the client must equal the METADATA_LOCATION_PROP currently in HMS. If they differ, another writer committed between this client's read and write, so a CommitFailedException is thrown and the caller must refresh and retry.

Source

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

        updateHiveView = true;
        LOG.debug("Committing existing view: {}", fullName);
      } else {
        tbl = newHMSView(metadata);
        LOG.debug("Committing new view: {}", fullName);
      }

      tbl.setSd(
          HiveOperationsBase.storageDescriptor(
              metadata.schema(),
              metadata.location(),
              hiveEngineEnabled)); // set to pick up any schema changes

      String metadataLocation =
          tbl.getParameters().get(BaseMetastoreTableOperations.METADATA_LOCATION_PROP);
      String baseMetadataLocation = base != null ? base.metadataFileLocation() : null;
      if (!Objects.equals(baseMetadataLocation, metadataLocation)) {
        throw new CommitFailedException(
            "Cannot commit: Base metadata location '%s' is not same as the current view metadata location '%s' for %s.%s",
            baseMetadataLocation, metadataLocation, database, viewName);
      }

      // get Iceberg props that have been removed
      Set<String> removedProps = emptySet();
      if (base != null) {
        removedProps =
            base.properties().keySet().stream()
                .filter(key -> !metadata.properties().containsKey(key))
                .collect(Collectors.toSet());
      }
      HMSTablePropertyHelper.updateHmsTableForIcebergView(
          newMetadataLocation,
          tbl,
          metadata,
          removedProps,
          maxHiveTablePropertySize,

View on GitHub (pinned to 86d9c8fc54)

Solutions

Refresh the view (loadView again) and re-apply the change, then commit — the standard optimistic retry loop.
Catch CommitFailedException in the caller and implement bounded retries with backoff.
Reduce concurrent writers to the same view or serialize view updates via orchestration.
Keep view handles short-lived so base metadata is not stale at commit time.

Example fix

// before
view.updateSchema().addColumn("c", Types.IntegerType.get()).commit(); // may fail
// after
int attempts = 3;
while (attempts-- > 0) {
  try {
    view = views.loadView(identifier);
    view.updateSchema().addColumn("c", Types.IntegerType.get()).commit();
    break;
  } catch (CommitFailedException e) { /* refresh and retry */ }
}

Defensive patterns

Strategy: retry

Validate before calling

// Verify base is current before commit
String current = hmsTable.getParameters().get(BaseMetastoreTableOperations.METADATA_LOCATION_PROP);
if (base != null && !base.metadataFileLocation().equals(current)) {
  // refresh and rebuild the update before attempting commit
}

Try / catch

int retries = 3;
while (retries-- > 0) {
  try {
    view = views.loadView(identifier);
    /* apply update */ .commit();
    break;
  } catch (CommitFailedException e) {
    if (retries == 0) throw e; // backoff then refresh-retry
  }
}

Prevention

Always implement a refresh-and-retry loop around view commits.
Keep view handles short-lived; reload before each update.
Limit concurrent writers per view or serialize updates.
Use backoff between retries to reduce repeated conflicts.

When it happens

Trigger: Committing a view update when a concurrent commit changed the view's metadata location in HMS after this client loaded it (base.metadataFileLocation() != current HMS value).

Common situations: Multiple concurrent writers to the same view; long-running jobs holding stale view handles; lost commit races under high write concurrency; retries with outdated base metadata.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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