apache/beam · error · ValueError

Unknown command possible values are

Error message

Unknown command %s possible values are %s

What it means

The beam_transform_service __main__ CLI validates known_args.command against _COMMAND_POSSIBLE_VALUES ('up', 'down', 'ps'). Any other value reaches main()'s else branch and raises ValueError listing the accepted commands.

Solutions

1. Use one of the supported commands: up, down, or ps (run `--help` to see them).
2. Fix typos in scripts/cron entries (e.g. 'stop' -> 'down', 'status' -> 'ps').
3. If programmatic control is needed, use TransformServiceLauncher methods (start/shutdown/status) instead of the CLI.
4. Validate the command argument in wrapper scripts before invoking the module.

Example fix

// before
python -m apache_beam.utils.transform_service_launcher start --address localhost --port 5000
// after
python -m apache_beam.utils.transform_service_launcher up --address localhost --port 5000

valid = {'up', 'down', 'ps'}
if command not in valid:
    sys.exit(f'invalid command {command!r}; expected one of {sorted(valid)}')

When it happens

Trigger: Running `python -m apache_beam.utils.transform_service_launcher <cmd> ...` (or the wrapper script) with a command other than up/down/ps, e.g. a typo like 'start', 'stop', or 'status'.

Common situations: Scripting service lifecycle from CI or notebooks and guessing the command name; docs referencing an older/newer CLI vocabulary; aliasing stop->down incorrectly.

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

• At least one of --render_port or --render_output must be…
• At most one of --create_test and --fix_tests may be…
• Encountered an Atomic type that is not currently supported…
• Exactly one of yaml_pipeline or yaml_pipeline_file must be…
• @on_timer decorator expected TimerSpec.

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

Appendix: source

Thrown at sdks/python/apache_beam/utils/transform_service_launcher.py:280

  project_name = (
      TransformServiceLauncher._DEFAULT_PROJECT_NAME
      if known_args.project_name is None else known_args.project_name)
  logging.info(
      'Starting the Beam Transform Service at %s.' % (
          'the default port' if known_args.port < 0 else
          (' port ' + str(known_args.port))))
  launcher = TransformServiceLauncher(
      project_name, known_args.port, known_args.beam_version)

  if known_args.command == 'up':
    launcher.start()
    launcher.wait_till_up(-1)
  elif known_args.command == 'down':
    launcher.shutdown()
  elif known_args.command == 'ps':
    launcher.status()
  else:
    raise ValueError(
        'Unknown command %s possible values are %s' %
        (known_args.command, ', '.join(_COMMAND_POSSIBLE_VALUES)))


if __name__ == '__main__':
  logging.getLogger().setLevel(logging.INFO)
  main(sys.argv)

View on GitHub (pinned to 12126d8942)