What causes "Unsupported format in USING: ${provider}" in apache/iceberg?

Use USING iceberg (or omit USING when the SparkSessionCatalog is configured as the default catalog) and set the file format with TBLPROPERTIES ('format-version'/'write.format.default' or a SUPPORTED provider)

apache/iceberg · error · IllegalArgumentException

Unsupported format in USING: ${provider}

Error message

Unsupported format in USING: ${provider}

What it means

Spark3Util.rebuildCreateProperties converts a Spark CREATE TABLE's USING provider into Iceberg default file-format table properties. Only parquet, avro, and orc are recognized; any other non-null provider (other than 'iceberg' itself) is rejected with this IllegalArgumentException so unsupported storage formats fail fast at table creation.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:130

    newOptions.put(key, value);
    return new CaseInsensitiveStringMap(newOptions);
  }

  public static Map<String, String> rebuildCreateProperties(Map<String, String> createProperties) {
    ImmutableMap.Builder<String, String> tableProperties = ImmutableMap.builder();
    createProperties.entrySet().stream()
        .filter(entry -> !RESERVED_PROPERTIES.contains(entry.getKey()))
        .forEach(tableProperties::put);

    String provider = createProperties.get(TableCatalog.PROP_PROVIDER);
    if ("parquet".equalsIgnoreCase(provider)) {
      tableProperties.put(TableProperties.DEFAULT_FILE_FORMAT, "parquet");
    } else if ("avro".equalsIgnoreCase(provider)) {
      tableProperties.put(TableProperties.DEFAULT_FILE_FORMAT, "avro");
    } else if ("orc".equalsIgnoreCase(provider)) {
      tableProperties.put(TableProperties.DEFAULT_FILE_FORMAT, "orc");
    } else if (provider != null && !"iceberg".equalsIgnoreCase(provider)) {
      throw new IllegalArgumentException("Unsupported format in USING: " + provider);
    }

    return tableProperties.build();
  }

  /**
   * Applies a list of Spark table changes to an {@link UpdateProperties} operation.
   *
   * @param pendingUpdate an uncommitted UpdateProperties operation to configure
   * @param changes a list of Spark table changes
   * @return the UpdateProperties operation configured with the changes
   */
  public static UpdateProperties applyPropertyChanges(
      UpdateProperties pendingUpdate, List<TableChange> changes) {
    for (TableChange change : changes) {
      if (change instanceof TableChange.SetProperty) {
        TableChange.SetProperty set = (TableChange.SetProperty) change;
        pendingUpdate.set(set.property(), set.value());

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use USING iceberg (or omit USING when the SparkSessionCatalog is configured as the default catalog) and set the file format with TBLPROPERTIES ('format-version'/'write.format.default' or a SUPPORTED provider)
Change USING to one of parquet, avro, or orc
If a non-Iceberg source format is needed, create the Iceberg table first and write into it from the source via DataFrame/SQL insert

Example fix

// before
CREATE TABLE t (...) USING csv;
// after
CREATE TABLE t (...) USING parquet; -- or USING iceberg

Defensive patterns

Strategy: validation

Validate before calling

if (provider != null && !Set.of("iceberg","parquet","avro","orc").contains(provider.toLowerCase(Locale.ROOT))) { throw new IllegalArgumentException("Unsupported format in USING: " + provider); }

Type guard

boolean isSupportedProvider(String p) { return p == null || Set.of("iceberg","parquet","avro","orc").contains(p.toLowerCase(Locale.ROOT)); }

Try / catch

try { Spark3Util.rebuildCreateProperties(desc); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unsupported format in USING")) { /* correct the USING clause */ } else throw e; }

Prevention

Always use USING iceberg or omit USING with a session catalog default
Only parquet/avro/orc are valid explicit providers with Iceberg DDL
Don't copy USING clauses from CSV/JSON/Delta examples
Add DDL linting in CI for CREATE TABLE statements

When it happens

Trigger: Running CREATE TABLE ... USING <provider> (via SparkCatalog/SparkSessionCatalog) where provider is not iceberg, parquet, avro, or orc — e.g. USING csv, USING json, USING text, or a custom DataSource.

Common situations: Copying DDL from non-Iceberg examples that used CSV/JSON sources; typo'd providers like 'parqet'; clustering tools that template USING clauses from Hive/Delta setups.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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