apache/beam · error · IllegalArgumentException

Class %s missing a property named '%s'.

Error message

Class %s missing a property named '%s'.

What it means

A value was supplied for an option property name that does not exist on the target PipelineOptions class, and no existing property is within Levenshtein distance 2 of the given name. Beam throws IllegalArgumentException during CLI/JSON option parsing.

Source

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

            Stream.concat(getRegisteredOptions().stream(), Stream.of(klass))
                .collect(Collectors.toSet()));
    for (PropertyDescriptor descriptor : propertyDescriptors) {
      propertyNamesToGetters.put(descriptor.getName(), descriptor.getReadMethod());
    }
    Map<String, Object> convertedOptions = Maps.newHashMap();
    for (final Map.Entry<String, Collection<String>> entry : options.asMap().entrySet()) {
      try {
        // 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());

View on GitHub (pinned to 12126d8942)

Solutions

  1. Correct the property name to exactly match a getter-derived property on the options class
  2. Run with --help=<class> to list valid properties for that options class
  3. Check for case/typo differences against the interface's getter names

Example fix

// before
PipelineOptionsFactory.fromArgs("--jobNmae=myjob").as(MyOptions.class);
// after
PipelineOptionsFactory.fromArgs("--jobName=myjob").as(MyOptions.class);
Defensive patterns

Strategy: validation

Validate before calling

Set<String> props = PropertyNames.methodToPropertyName(MyOptions.class.getMethods());
if (!props.contains("jobName")) throw new IllegalArgumentException("unknown option jobName; valid: " + props);

Try / catch

try { PipelineOptionsFactory.fromArgs(args).as(MyOptions.class); } catch (IllegalArgumentException e) { log.error("Bad option flag: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Calling PipelineOptionsFactory.fromArgs("--propName=value").as(...) or setting a JSON map key where no property named propName exists on the options class and no close match is found.

Common situations: Typo in the --flag name on the command line; renamed option property in a newer Beam version; case mismatch in the property name.

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/439b879adedf6445. Report an issue: GitHub.