apache/beam · error · IllegalArgumentException

Class %s missing a property named '%s'. Did you mean one of

Error message

Class %s missing a property named '%s'. Did you mean one of %s?

What it means

Same missing-property error, but multiple existing properties matched within Levenshtein distance 2, so the message lists all candidates: 'Did you mean one of [...]?'. Thrown during option name resolution in PipelineOptionsFactory.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsFactory.java:1902

        // Search for close matches for missing properties.
        // Either off by one or off by two character errors.
        if (!propertyNamesToGetters.containsKey(entry.getKey())) {
          SortedSet<String> closestMatches =
              new TreeSet<>(
                  Sets.filter(
                      propertyNamesToGetters.keySet(),
                      input -> StringUtils.getLevenshteinDistance(entry.getKey(), input) <= 2));
          switch (closestMatches.size()) {
            case 0:
              throw new IllegalArgumentException(
                  String.format("Class %s missing a property named '%s'.", klass, entry.getKey()));
            case 1:
              throw new IllegalArgumentException(
                  String.format(
                      "Class %s missing a property named '%s'. Did you mean '%s'?",
                      klass, entry.getKey(), Iterables.getOnlyElement(closestMatches)));
            default:
              throw new IllegalArgumentException(
                  String.format(
                      "Class %s missing a property named '%s'. Did you mean one of %s?",
                      klass, entry.getKey(), closestMatches));
          }
        }
        Method method = propertyNamesToGetters.get(entry.getKey());
        // Only allow empty argument values for String, String Array, and
        // Collection<String>.
        Class<?> returnType = method.getReturnType();
        JavaType type = MAPPER.getTypeFactory().constructType(method.getGenericReturnType());

        if ("runner".equals(entry.getKey())) {
          String runner = Iterables.getOnlyElement(entry.getValue());
          final Map<String, Class<? extends PipelineRunner<?>>> pipelineRunners =
              cache.supportedPipelineRunners;
          if (pipelineRunners.containsKey(runner.toLowerCase())) {
            convertedOptions.put("runner", pipelineRunners.get(runner.toLowerCase(ROOT)));
          } else {

View on GitHub (pinned to 12126d8942)

Solutions

Pick the correct property from the listed suggestions and fix the key
Print all properties with --help=<class> and verify against your call site
Remove the unknown key if it is no longer supported by the options class

Example fix

// before
options.setTempLocatio("gs://bucket/tmp");
// after
options.setTempLocation("gs://bucket/tmp");

Defensive patterns

Strategy: validation

Validate before calling

if (!knownProps.contains(key)) {
  List<String> close = Levenshtein.closest(knownProps, key, 2);
  throw new IllegalArgumentException("Unknown option " + key + "; did you mean " + close + "?");
}

Try / catch

catch (IllegalArgumentException e) { /* parse suggestions from message and retry with corrected key */ }

Prevention

Validate option maps against the interface's property set before creating the pipeline
Centralize option keys in an enum/constants class

When it happens

Trigger: Providing an option key that is ambiguous or misspelled near several real properties of the options class (edit distance <= 2 to more than one property).

Common situations: Misspelling a property in a family of similarly named options (e.g., zone/region/project style prefixes); programmatic option maps with stale keys.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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