apache/beam · error · IllegalArgumentException

Unknown command " ". Possible values are

Error message

Unknown command "%s". Possible values are {}

What it means

After config validation, main() dispatches on config.command against known values (e.g. "up", "down", "ps"). Any other non-empty command string falls through to this IllegalArgumentException, formatted with the offending command. Note the message uses String.format for %s but leaves a literal {} for the valid values list.

Solutions

1. Use one of the supported commands: up, down, ps (see COMMAND_POSSIBLE_VALUES in the launcher source).
2. Fix casing/typos — commands are matched with exact equals().
3. Check the launcher help text for the current command list in your Beam version.

Example fix

// before
--command=start

// after
--command=up

Set<String> valid = Set.of("up", "down", "ps");
if (!valid.contains(command))
  throw new IllegalArgumentException("Unknown command: " + command + "; valid: " + valid);

try {
  TransformServiceLauncher.main(rawArgs);
} catch (IllegalArgumentException e) {
  System.err.println(e.getMessage() + " — see launcher help for valid commands");
}

When it happens

Trigger: Invoking the launcher main with a --command value that is not one of the recognized commands (anything other than "up", "down", "ps", and the other handled command strings).

Common situations: Typos like --command=start or --command=deploy; passing a command from an older launcher version that was renamed; case mistakes ("UP" vs "up").

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

• " " argument must be specified.
• " " argument must be specified, Valid values are
• At least one of --render_port or --render_output must be…
• Batch size is too large! It should be smaller or equal than
• BigQuery %1$s not found for table "%2$s" . Please create…

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

Appendix: source

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

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

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

    if (config.command.equals("up")) {
      service.start();
      service.waitTillUp(-1);
    } else if (config.command.equals("down")) {
      service.shutdown();
    } else if (config.command.equals("ps")) {
      service.status();
    } else {
      throw new IllegalArgumentException(
          String.format("Unknown command \"%s\". Possible values are {}", config.command));
    }
  }
}

View on GitHub (pinned to 12126d8942)