apache/iceberg · error · IllegalArgumentException

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

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

An IllegalArgumentException from FlinkCatalog.createTable rejecting DDL that sets 'connector'='iceberg' in the table options while creating the table inside an Iceberg catalog. In an Iceberg catalog the connector property is implicit; explicitly passing it is only allowed for CREATE TABLE LIKE flows that carry the source-catalog marker property.

Solutions

1. Remove the 'connector'='iceberg' (and related) table options from the CREATE TABLE statement and just define columns/options.
2. If you need a Flink dynamic table over an existing Iceberg table, register a non-Iceberg catalog or use CREATE TABLE LIKE, which sets the required marker property.
3. Use the Iceberg catalog's table creation path (columns/partition-by/location options) instead of connector-style options.

Example fix

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

Map<String,String> opts = table.getOptions();
if ("iceberg".equals(opts.get("connector"))) { throw new IllegalArgumentException("drop connector option for iceberg catalog"); }

When it happens

Trigger: Running CREATE TABLE ... WITH ('connector'='iceberg') against an Iceberg catalog where the options contain FlinkCreateTableOptions.CONNECTOR_PROPS_KEY='iceberg' but lack the SRC_CATALOG_PROPS_KEY marker set by the LIKE/CTAS machinery.

Common situations: Users copying Flink SQL written for a generic (non-Iceberg) Flink catalog (e.g. filesystem/hive connector registration) and executing it against an Iceberg catalog; templated DDL generators that always emit the connector option; SQL client sessions configured with the Iceberg catalog but statements written for the default catalog.

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

• Altering partition keys is not supported yet.
• Cannot apply unknown modify-column change:
• Cannot apply unknown modify-column-position change:
• Cannot apply unknown table change:
• Cannot create the table with 'connector'='iceberg' table…

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

Appendix: source

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