apache/iceberg · error · IllegalArgumentException

Unknown file format %s

Error message

Unknown file format %s

What it means

SinkUtil.writeProperties builds format-specific compression properties and only handles PARQUET, AVRO, and ORC; any other FileFormat throws IllegalArgumentException 'Unknown file format %s'. It means the sink was asked to write a file format it cannot configure compression for (and by extension the write path does not support it).

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/SinkUtil.java:145

        if (parquetCompressionLevel != null) {
          writeProperties.put(PARQUET_COMPRESSION_LEVEL, parquetCompressionLevel);
        }

        break;
      case AVRO:
        writeProperties.put(AVRO_COMPRESSION, conf.avroCompressionCodec());
        String avroCompressionLevel = conf.avroCompressionLevel();
        if (avroCompressionLevel != null) {
          writeProperties.put(AVRO_COMPRESSION_LEVEL, conf.avroCompressionLevel());
        }

        break;
      case ORC:
        writeProperties.put(ORC_COMPRESSION, conf.orcCompressionCodec());
        writeProperties.put(ORC_COMPRESSION_STRATEGY, conf.orcCompressionStrategy());
        break;
      default:
        throw new IllegalArgumentException(String.format("Unknown file format %s", format));
    }

    return writeProperties;
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set write format to one of parquet, avro, or orc via FlinkWriteOptions.WRITE_FORMAT or the table's write.format.default property
2. If you need a newer format, upgrade iceberg-flink-runtime to a release that supports it in the sink
3. Check where format comes from (table properties vs write options) — a table property like write.format.default with a bad value must be corrected on the table
4. Validate format parsing before building the sink: FileFormat.fromString will throw earlier for bad strings

Example fix

// before
FlinkSink.forRowData(input).set("write-format", "json").tableLoader(loader).append();
// after
FlinkSink.forRowData(input).set("write-format", "parquet").tableLoader(loader).append();

String fmt = writeOptions.getOrDefault("write-format", table.properties().getOrDefault("write.format.default", "parquet"));
if (!Set.of("parquet", "avro", "orc").contains(fmt.toLowerCase(Locale.ROOT))) {
  throw new IllegalArgumentException("unsupported write-format: " + fmt);
}

try {
  sink.append();
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unknown file format")) {
    LOG.error("fix write-format/write.format.default to parquet|avro|orc");
  }
  throw e;
}

When it happens

Trigger: Setting format via FlinkWriteOptions.WRITE_FORMAT / 'write-format' to a value that resolves to a FileFormat outside the handled set (e.g. a table default write.format.default of parquet/orc/avro is fine, but programmatic FileFormat values or future formats are not), or passing a custom FileFormat enum constant.

Common situations: Configuring write-format with an unsupported/typo value in SQL hints or write options; using a new Iceberg format support (e.g. a format added in a newer release) with an older runtime; programmatic API misuse passing FileFormat values directly.

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

• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• ${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod
• Unrecognized :
• ${tableName}: Unrecognized write.distribution-mode: ${mode}

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