apache/beam · error · IllegalArgumentException

configuration with %s is not compatible with a %s format

Error message

configuration with %s is not compatible with a %s format

What it means

validateConfiguration enforces that a CsvConfiguration is only set when the format is "csv". If csvConfiguration is non-null but format is something else, it throws IllegalArgumentException stating the incompatibility. This catches contradictory configuration where sub-configs for one format are supplied with another format.

Source

Thrown at sdks/java/io/file-schema-transform/src/main/java/org/apache/beam/sdk/io/fileschematransform/FileWriteSchemaTransformProvider.java:174

                "%s is not a supported format. See %s for a list of supported formats.",
                configuration.getFormat(),
                FileWriteSchemaTransformFormatProviders.class.getName()));
      }
      // resolves [dereference.of.nullable]
      Optional<FileWriteSchemaTransformFormatProvider> provider =
          Optional.ofNullable(providers.get(configuration.getFormat()));
      checkState(provider.isPresent());
      return provider.get();
    }

    /**
     * Validates a {@link FileWriteSchemaTransformConfiguration} for correctness depending on its
     * {@link FileWriteSchemaTransformConfiguration#getFormat()}.
     */
    static void validateConfiguration(FileWriteSchemaTransformConfiguration configuration) {
      String format = configuration.getFormat();
      if (configuration.getCsvConfiguration() != null && !format.equals(CSV)) {
        throw new IllegalArgumentException(
            String.format(
                "configuration with %s is not compatible with a %s format",
                FileWriteSchemaTransformConfiguration.CsvConfiguration.class.getName(), format));
      }
      if (configuration.getParquetConfiguration() != null && !format.equals(PARQUET)) {
        throw new IllegalArgumentException(
            String.format(
                "configuration with %s is not compatible with a %s format",
                FileWriteSchemaTransformConfiguration.ParquetConfiguration.class.getName(),
                format));
      }
      if (configuration.getXmlConfiguration() != null && !format.equals(XML)) {
        throw new IllegalArgumentException(
            String.format(
                "configuration with %s is not compatible with a %s format",
                FileWriteSchemaTransformConfiguration.XmlConfiguration.class.getName(), format));
      }
      if (format.equals(AVRO) && !Strings.isNullOrEmpty(configuration.getCompression())) {

View on GitHub (pinned to 12126d8942)

Solutions

Remove setCsvConfiguration(...) when the format is not csv
Only attach the sub-configuration matching the chosen format (csv->CsvConfiguration, parquet->ParquetConfiguration, xml->XmlConfiguration)
If format comes from user input, validate format first and conditionally attach sub-configs
Simplify the config template so only the relevant sub-config block is present

Example fix

// before
FileWriteSchemaTransformConfiguration.builder()
    .setFormat("parquet")
    .setCsvConfiguration(CsvConfiguration.builder().build())
// after
FileWriteSchemaTransformConfiguration.builder()
    .setFormat("parquet")
    .setParquetConfiguration(ParquetConfiguration.builder().build())

Defensive patterns

Strategy: validation

Validate before calling

if (config.getCsvConfiguration() != null && !"csv".equals(config.getFormat()))
  throw new IllegalArgumentException("csvConfiguration requires format=csv");

Try / catch

// Validate before building the configuration
if (csvOpts != null && !"csv".equals(format)) {
  throw new IllegalArgumentException("Drop csvConfiguration when format is " + format);
}

Prevention

Build configurations with builder methods that pair format+subconfig in one helper
Never reuse a single config object across different format jobs
Add format-conditional logic wherever sub-configs are attached programmatically

When it happens

Trigger: FileWriteSchemaTransformConfiguration.builder().setFormat("parquet").setCsvConfiguration(CsvConfiguration.builder()...build()) — any non-CSV format combined with a non-null CsvConfiguration.

Common situations: Copy-pasting a configuration builder and changing the format but forgetting to remove setCsvConfiguration; building configs dynamically where CSV options are always attached; YAML/JSON config files carrying csv fields reused for parquet output.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/002236c84b5503f7. Report an issue: GitHub.