google/python-fire · error · ValueError

The command argument must be a string or a sequence of argum

Error message

The command argument must be a string or a sequence of arguments.

What it means

Python Fire's main entry point accepts the `command` argument as either a string (which it parses), a list/tuple of argument tokens, or None (to use sys.argv[1:]). This ValueError is raised for any other type, e.g. an int, dict, or a non-string element mismatch, since Fire cannot interpret it as a command to execute.

Source

Thrown at fire/core.py:117

  Raises:
    ValueError: If the command argument is supplied, but not a string or a
        sequence of arguments.
    FireExit: When Fire encounters a FireError, Fire will raise a FireExit with
        code 2. When used with the help or trace flags, Fire will raise a
        FireExit with code 0 if successful.
  """
  name = name or os.path.basename(sys.argv[0])

  # Get args as a list.
  if isinstance(command, str):
    args = shlex.split(command)
  elif isinstance(command, (list, tuple)):
    args = command
  elif command is None:
    # Use the command line args by default if no command is specified.
    args = sys.argv[1:]
  else:
    raise ValueError('The command argument must be a string or a sequence of '
                     'arguments.')

  args, flag_args = parser.SeparateFlagArgs(args)

  argparser = parser.CreateParser()
  parsed_flag_args, unused_args = argparser.parse_known_args(flag_args)

  context = {}
  if parsed_flag_args.interactive or component is None:
    # Determine the calling context.
    caller = inspect.stack()[1]
    caller_frame = caller[0]
    caller_globals = caller_frame.f_globals
    caller_locals = caller_frame.f_locals
    context.update(caller_globals)
    context.update(caller_locals)

  component_trace = _Fire(component, args, parsed_flag_args, context, name)

View on GitHub (pinned to 716bbc23d7)

Solutions

1. Convert the command to a string: fire.Fire(command=str(cmd))
2. Pass a list of string tokens instead: fire.Fire(command=['script.py','--flag','1'])
3. Pass nothing (None) so Fire uses sys.argv[1:]
4. Validate the command type before calling Fire

Example fix

// before
fire.Fire(command=config.get('command'))  # config value is a Path
// after
fire.Fire(command=[str(config.get('command'))])

cmd = config.get('command')
if not (cmd is None or isinstance(cmd, (str, list, tuple))):
    raise TypeError(f'command must be str/list/tuple/None, got {type(cmd).__name__}')
fire.Fire(component, command=cmd)

def is_valid_command(cmd) -> bool:
    return cmd is None or isinstance(cmd, (str, list, tuple))

try:
    fire.Fire(component, command=cmd)
except ValueError as e:
    if 'must be a string or a sequence' in str(e):
        sys.exit('invalid command argument')
    raise

When it happens

Trigger: Calling fire.Fire(command=123), fire.Fire(command={'a':1}), or passing a string-containing object that is not str/list/tuple/None. Also occurs when programmatic callers pass a parsed args object instead of a list of strings.

Common situations: Programmatic embedding of Fire in scripts or tests where the command is built dynamically (e.g. from config values that are not strings); passing a pathlib.Path object instead of str(command).

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Given file path does not exist.
• Unable to load module from specified path.
• Fire can only be called on .py files.
• Fire was passed a filename which could not be found.
• 2

AI-assisted analysis of google/python-fire@716bbc23d7 (2026-08-28). Data as JSON: /api/errors/ec5307eab4dcb1ca. Report an issue: GitHub.