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 an Iceberg table whose properties contain Flink's reserved keys CONNECTOR_PROPS_KEY or SRC_CATALOG_PROPS_KEY. These keys record how the table was created via Flink and are managed by the catalog; a source table already carrying them would produce ambiguous/conflicting connector configuration, so loading fails with IllegalArgumentException.

Source

Thrown at flink/v1.20/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. Remove the reserved keys (the connector/src-catalog property names shown in the message) from the Iceberg table properties: ALTER TABLE ... UNSET TBLPROPERTIES ('key').
2. Recreate the table via Flink normally instead of copying its property map.
3. Identify which tool injected the reserved keys and stop persisting them (filter them out in the property-copying code).
4. If the keys were set by mistake with correct values still needed, re-apply them only through the Flink catalog create path.

Example fix

// before: copying all props including reserved keys
newTable.updateProperties().setAll(source.properties()).commit();
// after
Map<String, String> safe = Maps.filterKeys(source.properties(),
    k -> !k.equals(FlinkCreateTableOptions.CONNECTOR_PROPS_KEY)
      && !k.equals(FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY));
newTable.updateProperties().setAll(safe).commit();

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

try {
  Table table = flinkCatalog.getTable(objectPath);
} catch (IllegalArgumentException e) {
  // unset reserved keys via a plain Catalog (not FlinkCatalog), then retry
}

When it happens

Trigger: Accessing (SELECT/scan/insert) an Iceberg table that was written by another tool or manually edited such that its properties include the Flink connector properties key or source-catalog properties key reserved by FlinkCreateTableOptions.

Common situations: A table created through Flink, then its properties copied wholesale into another table's properties (e.g. via CREATE TABLE ... LIKE or manual alter) and later read again from Flink; tooling that dumps and restores table properties including internal Flink keys.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Illegal table name:
• Namespaces are not supported by catalog:
• Database properties should not contain key: 'comment'.
• Can not alter the default database when the iceberg catalog
• Unknown catalog-type: %s (Must be 'hive', 'hadoop' or 'rest'

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