{"record":{"id":"578cec5d45f40a92","repo":"apache/iceberg","slug":"table-s-is-not-a-valid-bigquery-metastore-iceberg","errorCode":null,"errorMessage":"Table %s is not a valid BigQuery Metastore Iceberg table, metadata location not found","messagePattern":"Table (.+?) is not a valid BigQuery Metastore Iceberg table, metadata location not found","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryTableOperations.java","lineNumber":237,"sourceCode":"    }\n\n    Map<String, String> summary = metadata.currentSnapshot().summary();\n    if (summary.get(SnapshotSummary.TOTAL_DATA_FILES_PROP) != null) {\n      parameters.put(\"numFiles\", summary.get(SnapshotSummary.TOTAL_DATA_FILES_PROP));\n    }\n\n    if (summary.get(SnapshotSummary.TOTAL_RECORDS_PROP) != null) {\n      parameters.put(\"numRows\", summary.get(SnapshotSummary.TOTAL_RECORDS_PROP));\n    }\n\n    if (summary.get(SnapshotSummary.TOTAL_FILE_SIZE_PROP) != null) {\n      parameters.put(\"totalSize\", summary.get(SnapshotSummary.TOTAL_FILE_SIZE_PROP));\n    }\n  }\n\n  private String loadMetadataLocationOrThrow(ExternalCatalogTableOptions tableOptions) {\n    if (tableOptions == null || !tableOptions.getParameters().containsKey(METADATA_LOCATION_PROP)) {\n      throw new ValidationException(\n          \"Table %s is not a valid BigQuery Metastore Iceberg table, metadata location not found\",\n          tableName());\n    }\n\n    return tableOptions.getParameters().get(METADATA_LOCATION_PROP);\n  }\n}\n","sourceCodeStart":219,"sourceCodeEnd":245,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryTableOperations.java#L219-L245","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ncatalog.loadTable(TableIdentifier.of(\"my_dataset\", \"non_iceberg_table\"));\n// after\n// register the Iceberg table first, e.g. via a procedure or the BigQuery Metastore API\n// so parameters contains iceberg.metadata-location","handlingStrategy":"validation","validationCode":"// Confirm the table is an Iceberg-registered BQ Metastore table before loading:\n// fetch externalCatalogTableOptions via BigQuery API and check:\n// options != null && options.getParameters().containsKey(\"iceberg.metadata-location\")","typeGuard":null,"tryCatchPattern":"try {\n  Table t = catalog.loadTable(tableId);\n} catch (ValidationException e) {\n  if (e.getMessage().contains(\"metadata location not found\")) {\n    throw new IllegalStateException(tableId + \" is not an Iceberg table in BigQuery Metastore; register it first\", e);\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["bigquery","table-registration","validation"],"backgroundTag":"entity-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}