apache/iceberg · error · IllegalArgumentException

Unknown file format %s

Error message

Unknown file format %s

What it means

SinkUtil.writeProperties maps a FileFormat to compression properties for the sink; an unhandled format reaches the default branch and throws IllegalArgumentException("Unknown file format %s"). Only AVIF-free known formats (parquet, avro, orc) are covered by the switch.

Source

Thrown at flink/v2.2/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. Set write.format.default to parquet, avro, or orc.
2. Upgrade iceberg-flink-runtime if the format was added in a newer Iceberg release.
3. If calling writeProperties directly, only pass formats the switch implements.

Example fix

// before
options.put("write.format.default", "lance");
// after
options.put("write.format.default", "parquet");

FileFormat format = FileFormat.fromString(props.getProperty("write.format.default", "parquet"));
if (format != FileFormat.PARQUET && format != FileFormat.AVRO && format != FileFormat.ORC) {
  throw new IllegalArgumentException("Flink sink supports parquet/avro/orc only: " + format);
}

try {
  Map<String, String> props = SinkUtil.writeProperties(conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown file format")) {
    // fall back to parquet
  }
}

When it happens

Trigger: Calling SinkUtil.writeProperties (or configuring the sink's file format) with a FileFormat value outside the implemented set — e.g. a custom or newly added format not yet supported by the Flink sink's compression config.

Common situations: Setting write.format.default to an unsupported/newer value; running an older runtime against tables configured for a newer format; programmatic use of FileFormat.fromString with arbitrary input.

Related errors

• Unknown file format %s
• Unknown file format %s
• Unrecognized write.distribution-mode:
• Unrecognized write.distribution-mode:
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}

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