apache/beam · error · IllegalArgumentException

Invalid starting strategy. Valid values are: {values}

Error message

Invalid starting strategy. Valid values are: {values}

What it means

IcebergCdcReadSchemaTransformProvider.expand parses the starting_strategy configuration string into the StartingStrategy enum. If the provided value (uppercased) does not match any enum constant, IllegalArgumentException is thrown listing the valid values. This validates user-supplied configuration before building the CDC read.

Source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/IcebergCdcReadSchemaTransformProvider.java:101

        return SchemaRegistry.createDefault()
            .getToRowFunction(Configuration.class)
            .apply(configuration)
            .sorted()
            .toSnakeCase();
      } catch (NoSuchSchemaException e) {
        throw new RuntimeException(e);
      }
    }

    @Override
    public PCollectionRowTuple expand(PCollectionRowTuple input) {
      @Nullable String strategyStr = configuration.getStartingStrategy();
      StartingStrategy strategy = null;
      if (strategyStr != null) {
        Optional<StartingStrategy> optional =
            Enums.getIfPresent(StartingStrategy.class, strategyStr.toUpperCase());
        if (!optional.isPresent()) {
          throw new IllegalArgumentException(
              "Invalid starting strategy. Valid values are: "
                  + Arrays.toString(StartingStrategy.values()));
        }
        strategy = optional.get();
      }

      IcebergIO.ReadRows readRows =
          IcebergIO.readRows(configuration.getIcebergCatalog())
              .withCdc()
              .from(IcebergUtils.parseTableIdentifier(configuration.getTable()))
              .fromSnapshot(configuration.getFromSnapshot())
              .toSnapshot(configuration.getToSnapshot())
              .fromTimestamp(configuration.getFromTimestamp())
              .toTimestamp(configuration.getToTimestamp())
              .withStartingStrategy(strategy)
              .streaming(configuration.getStreaming())
              .keeping(configuration.getKeep())
              .dropping(configuration.getDrop())

View on GitHub (pinned to 12126d8942)

Solutions

Set starting_strategy to one of the valid StartingStrategy values (as printed in the error message).
Validate the option string against StartingStrategy values before submitting the pipeline.
Use Enums.getIfPresent with a default in programmatic construction, or rely on the enum constants in code rather than free-form strings.
Check the Beam version's StartingStrategy enum for the exact accepted names.

Example fix

// before
config.setStartingStrategy("startFromSnapshot");

// after (valid enum constant, e.g.)
config.setStartingStrategy("INCLUSIVE"); // must match StartingStrategy.values()

Defensive patterns

Strategy: validation

Validate before calling

boolean valid = strategyStr == null
    || Enums.getIfPresent(StartingStrategy.class, strategyStr.toUpperCase()).isPresent();
if (!valid) throw new IllegalArgumentException("bad starting_strategy: " + strategyStr);

Try / catch

try {
  transform.expand(input);
} catch (IllegalArgumentException e) {
  LOG.error("Invalid starting_strategy: {}", e.getMessage());
}

Prevention

Copy enum names directly from StartingStrategy.values().
Validate config strings before pipeline submission.
Pin and read the docs for your Beam version's accepted values.
Avoid hand-typed strategy strings in templates.

When it happens

Trigger: Setting starting_strategy in the IcebergCdcReadSchemaTransform configuration to a string other than the enum constants of StartingStrategy (e.g. a typo or unsupported casing of a word) at expand() time, IcebergCdcReadSchemaTransformProvider.java:101.

Common situations: Typo in YAML/JSON pipeline options (e.g. 'startAt' instead of a valid value); passing a value valid in a different Beam version that was renamed; constructing config programmatically with an unvalidated string.

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

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