google/python-fire · error · FireError

The argument '{argument}' is ambiguous as it could refer to

Error message

The argument '{argument}' is ambiguous as it could refer to any of the following arguments: {matching_fn_args}

What it means

Fire supports single-letter shortcut flags when exactly one function argument starts with that letter. If multiple arguments share the same first letter, the shortcut is ambiguous and FireError listing all matching_fn_args is raised instead of guessing.

Source

Thrown at fire/core.py:897

        value = None  # value will be set later on.

      key = key.replace('-', '_')
      is_bool_syntax = (not contains_equals and
                        (index + 1 == len(args) or _IsFlag(args[index + 1])))

      # Determine the keyword.
      keyword = ''  # Indicates no valid keyword has been found yet.
      if (key in fn_args
          or (is_bool_syntax and key.startswith('no') and key[2:] in fn_args)
          or fn_keywords):
        keyword = key
      elif len(key) == 1:
        # This may be a shortcut flag.
        matching_fn_args = [arg for arg in fn_args if arg[0] == key]
        if len(matching_fn_args) == 1:
          keyword = matching_fn_args[0]
        elif len(matching_fn_args) > 1:
          raise FireError(
              f"The argument '{argument}' is ambiguous as it could "
              f"refer to any of the following arguments: {matching_fn_args}"
          )

      # Determine the value.
      if not keyword:
        got_argument = False
      elif contains_equals:
        # Already got the value above.
        got_argument = True
      elif is_bool_syntax:
        # There's no next arg or the next arg is a Flag, so we consider this
        # flag to be a boolean.
        got_argument = True
        if keyword in fn_args:
          value = 'True'
        elif keyword.startswith('no'):
          keyword = keyword[2:]

View on GitHub (pinned to 716bbc23d7)

Solutions

1. Use the full flag name (--host=...) instead of the shortcut
2. Rename one of the colliding parameters
3. Add **kwargs or restructure args to avoid the first-letter collision

Example fix

// before
$ mytool connect -h=example.com  # host, header both match 'h'
// after
$ mytool connect --host=example.com

first_letters = [n[0] for n in inspect.signature(fn).parameters]
if len(first_letters) != len(set(first_letters)):
    print('warning: single-letter shortcut flags are ambiguous for this function')

try:
    fire.Fire(component)
except fire.core.FireError as e:
    if 'ambiguous' in str(e):
        print('use full flag names instead of shortcuts', file=sys.stderr)
        sys.exit(2)
    raise

When it happens

Trigger: Calling fn(host, hint) with -h=... (both start with 'h'); fn(port, path, protocol) with -p; using abbreviation flags on functions whose parameter names collide on the first character.

Common situations: Convenience one-letter flags colliding after adding new parameters; users assuming abbreviation works like argparse's prefix matching (it only matches first character and must be unique).

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.
• The command argument must be a string or a sequence of argum

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