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

FlinkCatalog.createTable rejects DDL that arrives with the Flink 'connector'='iceberg' option when the table is being created directly inside an Iceberg catalog. Iceberg tables already live in the Iceberg catalog, so a connector option is only meaningful when bridging from a non-Iceberg catalog (e.g. a generic/Hive path via CREATE TABLE ... LIKE). If the connector key is present and there is no source-catalog marker, the request is contradictory and fails fast with IllegalArgumentException.

Source

Thrown at flink/v1.20/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 (and related connector properties) when the catalog is already an Iceberg catalog — CREATE TABLE foo (...) suffices.
2. If bridging is intended, create the table in a non-Iceberg catalog with 'connector'='iceberg', or use CREATE TABLE ... LIKE so the SRC_CATALOG_PROPS_KEY marker is set.
3. Set the source-catalog properties option (FlinkCreateTableOptions.SRC_CATALOG_PROPS_KEY) if this table originates from another catalog's LIKE statement.

Example fix

// before
CREATE TABLE t WITH ('connector'='iceberg', 'path'='hdfs://...') AS SELECT ...
// after
CREATE TABLE t AS SELECT ...  -- when using an Iceberg catalog directly

boolean isIcebergCatalog = catalog instanceof org.apache.iceberg.flink.FlinkCatalog;
boolean setsConnector = table.getOptions().get("connector").equals("iceberg");
if (isIcebergCatalog && setsConnector) { throw new IllegalStateException("Do not pass connector=iceberg to an Iceberg catalog"); }

boolean isValidIcebergDdl(CatalogTable t) {
  return !("iceberg".equals(t.getOptions().get("connector")));
}

When it happens

Trigger: Calling CREATE TABLE with OPTIONS('connector'='iceberg') against a catalog resolved as an Iceberg catalog (FlinkCatalog), without the SRC_CATALOG_PROPS_KEY option that the LIKE-based bridge path sets. Any engine path that forwards FlinkDynamicTableFactory.FACTORY_IDENTIFIER in table options to createTable.

Common situations: Following generic Flink connector docs ('connector'='iceberg' in WITH/OPTIONS) while the catalog itself is already an Iceberg catalog; mixing Hive catalog syntax with Iceberg catalog DDL; copying examples meant for CREATE TABLE LIKE workflows.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

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/564e2ff0815082b7. Report an issue: GitHub.