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

createTable rejects a Flink table definition that explicitly sets 'connector'='iceberg' unless it carries the src-catalog property that marks it as derived via CREATE TABLE LIKE. Inside an Iceberg catalog the connector option is redundant and reserved, so a bare connector='iceberg' definition is treated as a misuse (usually copy-paste from a generic Flink catalog setup).

Source

Thrown at flink/v2.2/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

Remove the 'connector'='iceberg' option from the WITH clause when the table is created in an Iceberg catalog.
If this table was produced by CREATE TABLE LIKE from an Iceberg table, keep the like-origin property (do not strip the src-catalog key).
If the intent is a generic Flink connector table, create it in a non-Iceberg Flink catalog instead.

Example fix

// before
CREATE TABLE iceberg_catalog.db.t (id BIGINT) WITH ('connector'='iceberg');

// after
CREATE TABLE iceberg_catalog.db.t (id BIGINT) WITH ();

Defensive patterns

Strategy: validation

Validate before calling

if ("iceberg".equals(options.get("connector"))) {
  throw new IllegalArgumentException("drop 'connector'='iceberg' inside an iceberg catalog");
}

Try / catch

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

Prevention

In Iceberg catalogs, omit 'connector'='iceberg' from WITH clauses.
If using CREATE TABLE LIKE from an Iceberg table, keep the generated like-origin properties.
Lint generated DDL to strip connector options when the target catalog is Iceberg.

When it happens

Trigger: CREATE TABLE ... WITH ('connector'='iceberg') executed in an Iceberg catalog where the options map contains CONNECTOR_PROPS_KEY equal to 'iceberg' and SRC_CATALOG_PROPS_KEY is null (FlinkCatalog.java:416-423).

Common situations: Users following generic Flink SQL docs that require 'connector'='iceberg' for non-Iceberg catalogs, then running the same DDL in an Iceberg catalog; DDL generated by tools that always emit the connector option.

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

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