{"record":{"id":"ec5307eab4dcb1ca","repo":"google/python-fire","slug":"the-command-argument-must-be-a-string-or-a-sequenc","errorCode":null,"errorMessage":"The command argument must be a string or a sequence of arguments.","messagePattern":"The command argument must be a string or a sequence of arguments\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"fire/core.py","lineNumber":117,"sourceCode":"  Raises:\n    ValueError: If the command argument is supplied, but not a string or a\n        sequence of arguments.\n    FireExit: When Fire encounters a FireError, Fire will raise a FireExit with\n        code 2. When used with the help or trace flags, Fire will raise a\n        FireExit with code 0 if successful.\n  \"\"\"\n  name = name or os.path.basename(sys.argv[0])\n\n  # Get args as a list.\n  if isinstance(command, str):\n    args = shlex.split(command)\n  elif isinstance(command, (list, tuple)):\n    args = command\n  elif command is None:\n    # Use the command line args by default if no command is specified.\n    args = sys.argv[1:]\n  else:\n    raise ValueError('The command argument must be a string or a sequence of '\n                     'arguments.')\n\n  args, flag_args = parser.SeparateFlagArgs(args)\n\n  argparser = parser.CreateParser()\n  parsed_flag_args, unused_args = argparser.parse_known_args(flag_args)\n\n  context = {}\n  if parsed_flag_args.interactive or component is None:\n    # Determine the calling context.\n    caller = inspect.stack()[1]\n    caller_frame = caller[0]\n    caller_globals = caller_frame.f_globals\n    caller_locals = caller_frame.f_locals\n    context.update(caller_globals)\n    context.update(caller_locals)\n\n  component_trace = _Fire(component, args, parsed_flag_args, context, name)","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/google/python-fire/blob/716bbc23d7eca949fdb682172283c8d18f742cb6/fire/core.py#L99-L135","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Convert the command to a string: fire.Fire(command=str(cmd))","Pass a list of string tokens instead: fire.Fire(command=['script.py','--flag','1'])","Pass nothing (None) so Fire uses sys.argv[1:]","Validate the command type before calling Fire"],"exampleFix":"// before\nfire.Fire(command=config.get('command'))  # config value is a Path\n// after\nfire.Fire(command=[str(config.get('command'))])","handlingStrategy":"validation","validationCode":"cmd = config.get('command')\nif not (cmd is None or isinstance(cmd, (str, list, tuple))):\n    raise TypeError(f'command must be str/list/tuple/None, got {type(cmd).__name__}')\nfire.Fire(component, command=cmd)","typeGuard":"def is_valid_command(cmd) -> bool:\n    return cmd is None or isinstance(cmd, (str, list, tuple))","tryCatchPattern":"try:\n    fire.Fire(component, command=cmd)\nexcept ValueError as e:\n    if 'must be a string or a sequence' in str(e):\n        sys.exit('invalid command argument')\n    raise","preventionTips":["Only pass str, list/tuple of str, or None as command","Coerce Path/config values with str() before passing","Programmatically validate in tests that invoke Fire"],"tags":["python","argument-validation","cli"],"backgroundTag":"invalid-argument-type","analyzedSha":"716bbc23d7eca949fdb682172283c8d18f742cb6","analyzedAt":"2026-08-28T21:57:47.200Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}