apache/iceberg · error · IllegalArgumentException

Source table %s contains one/all of the reserved property ke

Error message

Source table %s contains one/all of the reserved property keys: %s, %s.

What it means

FlinkCatalog.getTable rejects Iceberg tables whose properties contain the reserved keys connector-type/src-catalog properties defined by FlinkCreateTableOptions. These keys are bookkeeping added by Flink for bridging non-iceberg catalogs; a source table in an iceberg catalog must never carry them, so the library fails with IllegalArgumentException.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:349

  }

  @Override
  public CatalogTable getTable(ObjectPath tablePath)
      throws TableNotExistException, CatalogException {
    Table table = loadIcebergTable(tablePath);

    // Flink's CREATE TABLE LIKE clause relies on properties sent back here to create new table.
    // As Flink API accepts only Map<String, String> for props, here we are serializing catalog
    // name, database, table as json string to distinguish between catalog info
    // and table properties in createTable.
    String srcCatalogProps =
        FlinkCreateTableOptions.toJson(
            getName(), tablePath.getDatabaseName(), tablePath.getObjectName());

    Map<String, String> tableProps = table.properties();
    if (tableProps.containsKey(FlinkCreateTableOptions.CONNECTOR_PROPS_KEY)
        || tableProps.containsKey(FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY)) {
      throw new IllegalArgumentException(
          String.format(
              "Source table %s contains one/all of the reserved property keys: %s, %s.",
              tablePath,
              FlinkCreateTableOptions.CONNECTOR_PROPS_KEY,
              FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY));
    }

    ImmutableMap.Builder<String, String> mergedProps = ImmutableMap.builder();
    mergedProps.put(
        FlinkCreateTableOptions.CONNECTOR_PROPS_KEY, FlinkDynamicTableFactory.FACTORY_IDENTIFIER);
    mergedProps.put(FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY, srcCatalogProps);
    mergedProps.putAll(tableProps);

    return toCatalogTableWithProps(table, mergedProps.build());
  }

  private Table loadIcebergTable(ObjectPath tablePath) throws TableNotExistException {
    try {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Recreate the table without the connector/src-catalog options so they are not persisted in Iceberg properties
2. Remove the reserved keys from the table properties via ALTER TABLE unset / updateProperties
3. Create such bridging tables only in non-iceberg catalogs and never copy their options across catalogs

Example fix

// before
String ddl = "CREATE TABLE t WITH ('connector'='iceberg', 'iceberg.catalog'='...')";
// after (in iceberg catalog)
String ddl = "CREATE TABLE t"; // no connector-related options

Map<String,String> props = table.properties();
if (props.containsKey("connector-type") || props.containsKey("src-catalog")) {
  throw new IllegalArgumentException("Table carries reserved Flink bridging property keys");
}

null

try { catalog.getTable(path); } catch (IllegalArgumentException e) { /* fix properties via table updateProperties */ }

When it happens

Trigger: Reading (getTable) a table whose metadata contains FlinkCreateTableOptions.CONNECTOR_PROPS_KEY or SRC_CATALOG_PROPS_KEY — usually because the table was created with connector='iceberg' options copied into its Iceberg properties.

Common situations: Tables created in a non-iceberg catalog and then registered/copied into an iceberg catalog with their Flink options intact; manual table metadata edits that leaked connector options into Iceberg table properties.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Database properties should not contain key: 'comment'.
• Cannot create the table with 'connector'='iceberg' table pro
• Namespaces are not supported by catalog:
• Can not alter the default database when the iceberg catalog
• Cannot create the table with 'connector'='iceberg' table pro

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