apache/beam · error · IllegalArgumentException

%s is not a supported format. See %s for a list of supported

Error message

%s is not a supported format. See %s for a list of supported formats.

What it means

FileWriteSchemaTransformProvider.getProvider loads all registered FileWriteSchemaTransformFormatProvider implementations (via ServiceLoader) and looks up the one named by configuration.getFormat(). If the requested format has no registered provider, it throws IllegalArgumentException listing where supported formats are enumerated. It means the requested output format isn't available at runtime.

Source

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

                                  .build()))
              .setRowSchema(OUTPUT_SCHEMA);

      if (files.has(ERROR_TAG)) {
        return PCollectionRowTuple.of(OUTPUT_TAG, output).and(ERROR_STRING, files.get(ERROR_TAG));
      } else {
        return PCollectionRowTuple.of(OUTPUT_TAG, output);
      }
    }

    /**
     * A helper method to retrieve the mapped {@link FileWriteSchemaTransformFormatProvider} from a
     * {@link FileWriteSchemaTransformConfiguration#getFormat()}.
     */
    FileWriteSchemaTransformFormatProvider getProvider() {
      Map<String, FileWriteSchemaTransformFormatProvider> providers =
          FileWriteSchemaTransformFormatProviders.loadProviders();
      if (!providers.containsKey(configuration.getFormat())) {
        throw new IllegalArgumentException(
            String.format(
                "%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();

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a supported format string: csv, parquet, avro, json, xml (see FileWriteSchemaTransformFormatProviders javadoc)
2. Check the format string for typos and case (lowercase required)
3. If using a custom format, register its provider in META-INF/services and ensure the jar is on the classpath
4. Print FileWriteSchemaTransformFormatProviders.loadProviders().keySet() to see available formats

Example fix

// before
FileWriteSchemaTransformConfiguration.builder().setFormat("xlsx")...
// after
FileWriteSchemaTransformConfiguration.builder().setFormat("parquet")...

Set<String> supported = FileWriteSchemaTransformFormatProviders.loadProviders().keySet();
if (!supported.contains(format.toLowerCase()))
  throw new IllegalArgumentException("Format " + format + " not supported. Use one of " + supported);

try {
  transform(configuration);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("is not a supported format"))
    LOG.error("Use one of: {}", FileWriteSchemaTransformFormatProviders.loadProviders().keySet());
  throw e;
}

When it happens

Trigger: FileWriteSchemaTransformConfiguration.builder().setFormat("xlsx") (or any format other than the registered ones like csv, parquet, avro, json, xml) applied through the write transform; case mismatch like "CSV" instead of "csv".

Common situations: Typo in format string; uppercase format; missing service-provider registration (META-INF/services) when using a custom provider; user assumed a format is supported without checking the provider list.

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

• Failed to validate %s
• Secret string must contain a valid type parameter
• %s expects a single %s tagged PCollection<Row> input
• configuration with %s is not compatible with a %s format
• To read from Pubsub, a subscription name or a topic name mus

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