apache/iceberg · error · IllegalArgumentException

Cannot create the table with 'connector'='iceberg' table pro

Error message

Cannot create the table with 'connector'='iceberg' table property in an iceberg catalog, Please create table with 'connector'='iceberg' property in a non-iceberg catalog or create table without 'connector'='iceberg' related properties in an iceberg table.

What it means

In an Iceberg catalog, creating a table that explicitly sets 'connector'='iceberg' is redundant and only valid when the table is created via LIKE from a source catalog table (indicated by the src-catalog property being set). The library throws IllegalArgumentException to stop users from persisting Flink connector options into Iceberg table metadata.

Source

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

          toIdentifier(new ObjectPath(tablePath.getDatabaseName(), newTableName)));
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      if (!ignoreIfNotExists) {
        throw new TableNotExistException(getName(), tablePath, e);
      }
    } catch (AlreadyExistsException e) {
      throw new TableAlreadyExistException(getName(), tablePath, e);
    }
  }

  @Override
  public void createTable(ObjectPath tablePath, CatalogBaseTable table, boolean ignoreIfExists)
      throws CatalogException, TableAlreadyExistException {
    // Creating Iceberg table using connector is allowed only when table is created using LIKE
    if (Objects.equals(
            table.getOptions().get(FlinkCreateTableOptions.CONNECTOR_PROPS_KEY),
            FlinkDynamicTableFactory.FACTORY_IDENTIFIER)
        && table.getOptions().get(FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY) == null) {
      throw new IllegalArgumentException(
          "Cannot create the table with 'connector'='iceberg' table property in "
              + "an iceberg catalog, Please create table with 'connector'='iceberg' property in a non-iceberg catalog or "
              + "create table without 'connector'='iceberg' related properties in an iceberg table.");
    }

    Preconditions.checkArgument(
        table instanceof ResolvedCatalogTable,
        "Expected a ResolvedCatalogTable but got: %s. "
            + "Iceberg Flink catalog only supports resolved catalog tables "
            + "(Materialized tables and other table kinds are not supported).",
        table == null ? "null" : table.getClass().getName());
    createIcebergTable(tablePath, (ResolvedCatalogTable) table, ignoreIfExists);
  }

  void createIcebergTable(ObjectPath tablePath, ResolvedCatalogTable table, boolean ignoreIfExists)
      throws CatalogException, TableAlreadyExistException {
    validateFlinkTable(table);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Remove the 'connector'='iceberg' option from the WITH clause when the catalog is already an iceberg catalog
2. If bridging from a source catalog, use CREATE TABLE LIKE so SRC_CATALOG_PROPS_KEY is set
3. Strip connector-related options from generated DDL when targeting iceberg catalogs

Example fix

// before
CREATE TABLE t (id INT) WITH ('connector'='iceberg');
// after
CREATE TABLE t (id INT);

if ("iceberg".equals(options.get("connector")) && icebergCatalogUsed) {
  throw new IllegalArgumentException("Drop 'connector'='iceberg' when using an iceberg catalog");
}

null

try { catalog.createTable(path, table, ignoreIfExists); } catch (IllegalArgumentException e) { /* strip connector options and retry */ }

When it happens

Trigger: CREATE TABLE ... WITH ('connector'='iceberg') executed against an iceberg catalog where the option map contains CONNECTOR_PROPS_KEY='iceberg' and SRC_CATALOG_PROPS_KEY is null (not a LIKE-created table).

Common situations: Copy-pasting DDL written for a generic Flink catalog into an iceberg catalog; migration scripts that template connector options into every CREATE TABLE.

Related errors

• Cannot create the table with 'connector'='iceberg' table pro
• Altering partition keys is not supported yet.
• Unsupported table change: AddWatermark.
• Unsupported table change: ModifyWatermark.
• Unsupported table change: DropWatermark.

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