apache/iceberg · error · ConfigException

Must specify table name(s)

Error message

Must specify table name(s)

What it means

IcebergSinkConfig.validate throws ConfigException when neither static table names nor dynamic table routing is configured. The Iceberg Kafka Connect sink requires at least one of iceberg.tables or iceberg.tables.dynamic-enabled with a route field.

Source

Thrown at kafka-connect/kafka-connect/src/main/java/org/apache/iceberg/connect/IcebergSinkConfig.java:294

    jsonConverter.configure(
        ImmutableMap.of(
            JsonConverterConfig.SCHEMAS_ENABLE_CONFIG,
            false,
            ConverterConfig.TYPE_CONFIG,
            ConverterType.VALUE.getName()));

    validate();
  }

  private void validate() {
    checkState(!catalogProps().isEmpty(), "Must specify Iceberg catalog properties");
    if (tables() != null) {
      checkState(!dynamicTablesEnabled(), "Cannot specify both static and dynamic table names");
    } else if (dynamicTablesEnabled()) {
      checkState(
          tablesRouteField() != null, "Must specify a route field if using dynamic table names");
    } else {
      throw new ConfigException("Must specify table name(s)");
    }
  }

  private void checkState(boolean condition, String msg) {
    if (!condition) {
      throw new ConfigException(msg);
    }
  }

  public String connectorName() {
    return originalProps.get(NAME_PROP);
  }

  public String taskId() {
    return originalProps.get(TASK_ID);
  }

  public String transactionalSuffix() {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set 'iceberg.tables' to a comma-separated list of destination table names.
2. Or enable dynamic routing: set 'iceberg.tables.dynamic-enabled=true' and provide 'iceberg.tables.route-field'.
3. Verify the connector properties file uses exact property key names.

Example fix

// before
"iceberg.catalog": "hadoop"
// after
"iceberg.catalog": "hadoop",
"iceberg.tables": "db.table1,db.table2"

// Validate connector config before submission
if (config.get("iceberg.tables") == null && !Boolean.parseBoolean(config.getOrDefault("iceberg.tables.dynamic-enabled", "false"))) {
  throw new IllegalArgumentException("set iceberg.tables or enable iceberg.tables.dynamic-enabled");
}

try { new IcebergSinkConfig(props); } catch (org.apache.kafka.common.config.ConfigException e) { log.error("Sink config invalid: {}", e.getMessage()); }

When it happens

Trigger: Creating an IcebergSinkConfig (connector start) with iceberg.tables unset and iceberg.tables.dynamic-enabled=false (default).

Common situations: Missing iceberg.tables property in the connector config; typo in the property name; enabling dynamic routing but forgetting to also remove the static-list requirement path.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• ${msg}
• Invalid rewrite job order name: %s
• Unknown row-level operation mode:
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}

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