apache/iceberg · error · IllegalArgumentException

Unknown file format %s

Error message

Unknown file format %s

What it means

SinkUtil.writeProperties computes per-format compression properties, and throws IllegalArgumentException when the table's file format is not one of PARQUET, AVRO, or ORC. Iceberg tables only support these three formats, so this indicates a corrupted or unsupported write.file-format value.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/SinkUtil.java:151

        writeProperties.put(PARQUET_SHRED_VARIANTS, String.valueOf(conf.parquetShredVariants()));
        writeProperties.put(
            PARQUET_VARIANT_BUFFER_SIZE, String.valueOf(conf.parquetVariantInferenceBufferSize()));

        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. Ensure the table's write.format.default is parquet, avro, or orc (ALTER TABLE ... SET TBLPROPERTIES ('write.format.default'='parquet')).
2. If this occurs with a newer format added upstream, upgrade the Iceberg Flink runtime JAR to match the writer that produced the metadata.
3. Check for a locally modified FileFormat enum and add the missing case to the switch in SinkUtil.

Example fix

// before: 'write.format.default'='iceberg-custom-format'
// after
ALTER TABLE db.t SET TBLPROPERTIES ('write.format.default'='parquet');

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

When it happens

Trigger: Calling SinkUtil.writeProperties with a table whose write.format.default (FileFormat) is something other than PARQUET/AVRO/ORC, which practically means a manually constructed FileFormat or a modified table metadata.

Common situations: Custom/extended builds adding a new format without updating this switch; tests constructing FileFormat values directly; version skew where a newer writer added a format an older SinkUtil doesn't know.

Related errors

• Unrecognized write.distribution-mode: ${mode}
• Unknown file format %s
• Unknown row kind: <row.getRowKind()>
• Unknown file format %s
• Unknown row kind:

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