apache/beam · error · IllegalArgumentException

" " argument must be specified, Valid values are

Error message

"{ArgConfig.COMMAND_ARG_NAME}" argument must be specified, Valid values are {COMMAND_POSSIBLE_VALUES}

What it means

The launcher's main() validates its parsed ArgConfig before executing: a command (up/down/ps-style value from COMMAND_POSSIBLE_VALUES) must be supplied. If config.command is empty, it throws this IllegalArgumentException naming the required argument and the valid values.

Solutions

1. Pass the command argument, e.g. --command=up (valid values listed in COMMAND_POSSIBLE_VALUES: up, down, ps, upgrade-style commands).
2. Check the launcher's help/usage output (it prints usage when args are invalid) for exact flag names.
3. Fix typos in the flag name so the value is actually parsed into config.command.

Example fix

// before
java -jar transform-service-launcher.jar --beam_version=2.59.0

// after
java -jar transform-service-launcher.jar --command=up --beam_version=2.59.0

Map<String,String> args = parseArgs(rawArgs);
if (!args.containsKey("command") || args.get("command").isEmpty())
  throw new IllegalArgumentException("--command must be specified");

try {
  TransformServiceLauncher.main(rawArgs);
} catch (IllegalArgumentException e) {
  System.err.println(e.getMessage());
  TransformServiceLauncher.main(new String[]{}); // prints usage
}

When it happens

Trigger: Running the TransformServiceLauncher main class without the --command (ArgConfig.COMMAND_ARG_NAME) argument, or passing an empty value for it.

Common situations: Invoking java -jar ...launcher.jar with only --beam_version set; scripting the launcher and forgetting the command flag; typo of the flag name so it is not parsed as the command argument.

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

• " " argument must be specified.
• Unknown command " ". Possible values are
• A function must be provided to convert the input type into…
• At least one of --render_port or --render_output must be…
• Batch size is too large! It should be smaller or equal than

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

Appendix: source

Thrown at sdks/java/transform-service/launcher/src/main/java/org/apache/beam/sdk/transformservice/launcher/TransformServiceLauncher.java:373

  public static void main(String[] args) throws IOException, TimeoutException {

    ArgConfig config = new ArgConfig();
    CmdLineParser parser = new CmdLineParser(config);

    try {
      parser.parseArgument(args);
    } catch (CmdLineException e) {
      System.err.println(e.getMessage());
      System.err.println("Valid options are:");
      // print the list of available options
      parser.printUsage(System.err);
      System.err.println();

      return;
    }

    if (config.command.isEmpty()) {
      throw new IllegalArgumentException(
          "\""
              + ArgConfig.COMMAND_ARG_NAME
              + "\" argument must be specified, Valid values are "
              + COMMAND_POSSIBLE_VALUES);
    }
    if (config.beamVersion.isEmpty()) {
      throw new IllegalArgumentException(
          "\"" + ArgConfig.BEAM_VERSION_ARG_NAME + "\" argument must be specified.");
    }

    System.out.println("===================================================");
    System.out.println(
        "Starting the Beam Transform Service at "
            + (config.port < 0
                ? "the default port."
                : ("port " + Integer.toString(config.port) + ".")));
    System.out.println("===================================================");

View on GitHub (pinned to 12126d8942)