apache/beam · error · IllegalArgumentException

Missing required value for group [<group>]. At least one of

Error message

Missing required value for group [<group>]. At least one of the following properties <properties> required. Run with --help=<class> for more information.

What it means

PipelineOptionsValidator found a @Validation.Required group (@Validation.Group annotation) whose properties are all unset. At least one property in the group must be given; the error names the group, its properties, and points to --help=<class>. Thrown from PipelineOptionsValidator.validate().

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsValidator.java:111

            checkArgument(
                handler.invoke(asClassOptions, method, null) != null,
                "Missing required value for [--%s, \"%s\"]. ",
                handler.getOptionName(method),
                getDescription(method));
          } else {
            checkArgument(
                handler.invoke(asClassOptions, method, null) != null,
                "Missing required value for [%s, \"%s\"]. ",
                method,
                getDescription(method));
          }
        }
      }
    }

    for (String requiredGroup : requiredGroups.keySet()) {
      if (!verifyGroup(handler, asClassOptions, requiredGroups.get(requiredGroup))) {
        throw new IllegalArgumentException(
            "Missing required value for group ["
                + requiredGroup
                + "]. At least one of the following properties "
                + Collections2.transform(
                    requiredGroups.get(requiredGroup), ReflectHelpers::formatMethod)
                + " required. Run with --help="
                + klass.getSimpleName()
                + " for more information.");
      }
    }

    return asClassOptions;
  }

  private static boolean verifyGroup(
      ProxyInvocationHandler handler, PipelineOptions options, Collection<Method> requiredGroup) {
    for (Method m : requiredGroup) {
      if (handler.invoke(options, m, null) != null) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Set at least one required property of the named group before validation
2. Run --help=<class> to see which properties satisfy the group
3. Adjust the @Validation.Group declaration if the requirement is outdated

Example fix

// before
DataflowPipelineOptions opts = PipelineOptionsFactory.as(DataflowPipelineOptions.class);
Pipeline.create(opts); // group properties unset
// after
opts.setProject("my-project");
opts.setRegion("us-central1");
opts.setStagingLocation("gs://bucket/staging");
Pipeline.create(opts);

Set<Method> groupMembers = groupPropsOf(MyOptions.class); // from @Validation.Group
if (groupMembers.stream().allMatch(m -> safeGet(opts, m) == null)) throw new IllegalStateException("required group unset");

try { PipelineOptionsValidator.validate(cli, opts); } catch (IllegalArgumentException e) { log.error("Required group missing: {}", e.getMessage()); }

When it happens

Trigger: Validating options whose interface declares a required group, e.g. @Validation.Required groups like GCS/BigQuery options, without setting any member property, via Pipeline.create(options) or validateCli.

Common situations: Launching a Dataflow pipeline without specifying project/region/stagingLocation group members; refactor removed the option that satisfied the group; templating left all group members empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --maxCacheMemoryUsagePercent must be between 0 and 100.
• GroupByEncryptedKey requires its input to use KvCoder
• the GroupByKey requires its output coder to be %s but found
• Expected size >= 0 but received ${size}.
• Expected to have found at most one parameter of type %s but

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