apache/iceberg · error · ValidationException

Table %s is not a valid BigQuery Metastore Iceberg table, me

Error message

Table %s is not a valid BigQuery Metastore Iceberg table, metadata location not found

What it means

loadMetadataLocationOrThrow validates that the BigQuery Metastore table's ExternalCatalogTableOptions parameters contain the metadata_location property. If tableOptions is null or the key is absent, the table is not an Iceberg table managed via BigQuery Metastore, so a ValidationException is thrown during doRefresh.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryTableOperations.java:237

    }

    Map<String, String> summary = metadata.currentSnapshot().summary();
    if (summary.get(SnapshotSummary.TOTAL_DATA_FILES_PROP) != null) {
      parameters.put("numFiles", summary.get(SnapshotSummary.TOTAL_DATA_FILES_PROP));
    }

    if (summary.get(SnapshotSummary.TOTAL_RECORDS_PROP) != null) {
      parameters.put("numRows", summary.get(SnapshotSummary.TOTAL_RECORDS_PROP));
    }

    if (summary.get(SnapshotSummary.TOTAL_FILE_SIZE_PROP) != null) {
      parameters.put("totalSize", summary.get(SnapshotSummary.TOTAL_FILE_SIZE_PROP));
    }
  }

  private String loadMetadataLocationOrThrow(ExternalCatalogTableOptions tableOptions) {
    if (tableOptions == null || !tableOptions.getParameters().containsKey(METADATA_LOCATION_PROP)) {
      throw new ValidationException(
          "Table %s is not a valid BigQuery Metastore Iceberg table, metadata location not found",
          tableName());
    }

    return tableOptions.getParameters().get(METADATA_LOCATION_PROP);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Verify the table is actually an Iceberg table registered in BigQuery Metastore with metadata_location in its parameters.
Check you are pointing at the correct table/project — a same-named non-Iceberg table is a common cause.
Re-register the table with the correct metadata location, or recreate it through the Iceberg catalog.
Inspect the table's externalCatalogTableOptions via the BigQuery API to confirm which parameters are present.

Example fix

// before
catalog.loadTable(TableIdentifier.of("my_dataset", "non_iceberg_table"));
// after
// register the Iceberg table first, e.g. via a procedure or the BigQuery Metastore API
// so parameters contains iceberg.metadata-location

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the table is an Iceberg-registered BQ Metastore table before loading:
// fetch externalCatalogTableOptions via BigQuery API and check:
// options != null && options.getParameters().containsKey("iceberg.metadata-location")

Try / catch

try {
  Table t = catalog.loadTable(tableId);
} catch (ValidationException e) {
  if (e.getMessage().contains("metadata location not found")) {
    throw new IllegalStateException(tableId + " is not an Iceberg table in BigQuery Metastore; register it first", e);
  }
  throw e;
}

Prevention

Create tables through the Iceberg catalog so metadata_location is always set
Verify with the BigQuery API that the target table has external catalog Iceberg parameters before loading
Check dataset/table names to avoid resolving to a same-named native BigQuery table
Never hand-edit the table's parameters map

When it happens

Trigger: Loading/refreshing a table whose metastore entry has no metadata_location parameter: the table exists in BigQuery Metastore but was not created as an Iceberg table, or its external catalog options were wiped.

Common situations: Pointing an Iceberg catalog at a plain BigQuery table or a table created by another integration; the table's parameters were manually edited/removed; partial table migration left options unset.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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