apache/iceberg · error · NoSuchTableException

Unknown metadata table type

Error message

Unknown metadata table type: %s for %s

What it means

NoSuchTableException thrown when the requested metadata table type is not recognized in the switch over MetadataTableType. The metadata table name parsed to a type that has no corresponding implementation table, so instance creation fails. This typically results from a version mismatch or an invalid/unknown metadata table name suffix.

Solutions

1. Upgrade the Iceberg runtime to a version that supports the requested metadata table type.
2. Check the metadata table name suffix against supported types (snapshots, files, history, refs, manifests, all_*, entries, position_deletes, partitions, metadata_log_entries).
3. Catch NoSuchTableException and fall back to a supported metadata table type.
4. Regenerate/fix tooling that constructs metadata table names programmatically.

Example fix

// before
Table t = MetadataTableUtils.createMetadataTableInstance(ops, "db.tbl", "db.tbl.filess", type); // NoSuchTableException
// after
Table t = MetadataTableUtils.createMetadataTableInstance(ops, "db.tbl", "db.tbl.files", MetadataTableType.FILES);

// ensure the type is a known MetadataTableType and name matches
String name = tableName + "." + type.displayName();

try {
  Table meta = MetadataTableUtils.createMetadataTableInstance(ops, baseName, metaName, type);
} catch (NoSuchTableException e) {
  // fall back to a supported metadata table type or upgrade runtime
}

When it happens

Trigger: Calling createMetadataTableInstance(ops, name, metadataTableName, type) with a MetadataTableType that has no case (e.g., a newly added type used against an older Iceberg runtime), or constructing a metadata table name with an unrecognized suffix.

Common situations: Mixing Iceberg versions (engine runtime older than the catalog/client that referenced a new metadata table type); typo in metadata table name like 'tbl.filess'; custom tooling emitting unsupported type identifiers.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot apply unknown table change:
• Cannot apply unknown unique constraint:
• Cannot convert unknown type to Flink
• Cannot convert unsupported type to Spark:
• Cannot convert unsupported type to Spark:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/MetadataTableUtils.java:92

        return new RefsTable(baseTable, metadataTableName);
      case MANIFESTS:
        return new ManifestsTable(baseTable, metadataTableName);
      case PARTITIONS:
        return new PartitionsTable(baseTable, metadataTableName);
      case ALL_DATA_FILES:
        return new AllDataFilesTable(baseTable, metadataTableName);
      case ALL_DELETE_FILES:
        return new AllDeleteFilesTable(baseTable, metadataTableName);
      case ALL_FILES:
        return new AllFilesTable(baseTable, metadataTableName);
      case ALL_MANIFESTS:
        return new AllManifestsTable(baseTable, metadataTableName);
      case ALL_ENTRIES:
        return new AllEntriesTable(baseTable, metadataTableName);
      case POSITION_DELETES:
        return new PositionDeletesTable(baseTable, metadataTableName);
      default:
        throw new NoSuchTableException(
            "Unknown metadata table type: %s for %s", type, metadataTableName);
    }
  }

  public static Table createMetadataTableInstance(
      TableOperations ops,
      String catalogName,
      TableIdentifier baseTableIdentifier,
      TableIdentifier metadataTableIdentifier,
      MetadataTableType type) {
    String baseTableName = BaseMetastoreCatalog.fullTableName(catalogName, baseTableIdentifier);
    String metadataTableName =
        BaseMetastoreCatalog.fullTableName(catalogName, metadataTableIdentifier);
    return createMetadataTableInstance(ops, baseTableName, metadataTableName, type);
  }

  private static String metadataTableName(String tableName, MetadataTableType type) {
    return tableName + (tableName.contains("/") ? "#" : ".") + type.name().toLowerCase(Locale.ROOT);

View on GitHub (pinned to 86d9c8fc54)