apache/beam · error · IllegalArgumentException

" " argument must be specified.

Error message

"{ArgConfig.BEAM_VERSION_ARG_NAME}" argument must be specified.

What it means

Immediately after validating the command, main() requires a Beam version (ArgConfig.BEAM_VERSION_ARG_NAME) used to select/pull the matching transform-service image. If config.beamVersion is empty, it throws this IllegalArgumentException.

Solutions

1. Pass the Beam version explicitly, e.g. --beam_version=2.59.0, matching your Beam SDK version.
2. Fix any shell variable interpolation so the version value is not empty.
3. Check usage output for the exact argument name (ArgConfig.BEAM_VERSION_ARG_NAME).

Example fix

// before (shell)
java -jar launcher.jar --command=up --beam_version=""

// after (shell)
java -jar launcher.jar --command=up --beam_version=2.59.0

String beamVersion = System.getenv().getOrDefault("BEAM_VERSION", "");
if (beamVersion.isEmpty())
  throw new IllegalArgumentException("BEAM_VERSION must be set before invoking the launcher");

try {
  TransformServiceLauncher.main(rawArgs);
} catch (IllegalArgumentException e) {
  System.err.println("Launcher arg problem: " + e.getMessage());
}

When it happens

Trigger: Running the launcher main with --command provided but without the Beam version argument, or providing an empty value for it.

Common situations: Scripts templated with an unset ${BEAM_VERSION} variable expanding to empty; forgetting the flag when upgrading; flag name typo so the value never lands in config.beamVersion.

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, Valid values are
• 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/70166bd6311bb2e3. Report an issue: GitHub.

Appendix: source

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

    } 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("===================================================");

    String pythonRequirementsFile =
        !config.pythonRequirementsFile.isEmpty() ? config.pythonRequirementsFile : null;

    TransformServiceLauncher service =
        TransformServiceLauncher.forProject(
            config.projectName, config.port, pythonRequirementsFile);
    if (!config.beamVersion.isEmpty()) {

View on GitHub (pinned to 12126d8942)