google/python-fire · error · FireError

Unexpected kwargs present:

Error message

Unexpected kwargs present:

What it means

When calling a function, Fire collects keyword flags into kwargs. If the function's signature has no **kwargs catch-all (varkw is None) and the caller supplied keyword flags that aren't among the function's keyword-only parameters, FireError('Unexpected kwargs present:', extra_kw) is raised listing the offending names.

Source

Thrown at fire/core.py:739

  num_required_args = len(fn_spec.args) - len(fn_spec.defaults)
  required_kwonly = set(fn_spec.kwonlyargs) - set(fn_spec.kwonlydefaults)

  def _ParseFn(args):
    """Parses the list of `args` into (varargs, kwargs), remaining_args."""
    kwargs, remaining_kwargs, remaining_args = _ParseKeywordArgs(args, fn_spec)

    # Note: _ParseArgs modifies kwargs.
    parsed_args, kwargs, remaining_args, capacity = _ParseArgs(
        fn_spec.args, fn_spec.defaults, num_required_args, kwargs,
        remaining_args, metadata)

    if fn_spec.varargs or fn_spec.varkw:
      # If we're allowed *varargs or **kwargs, there's always capacity.
      capacity = True

    extra_kw = set(kwargs) - set(fn_spec.kwonlyargs)
    if fn_spec.varkw is None and extra_kw:
      raise FireError('Unexpected kwargs present:', extra_kw)

    missing_kwonly = set(required_kwonly) - set(kwargs)
    if missing_kwonly:
      raise FireError('Missing required flags:', missing_kwonly)

    # If we accept *varargs, then use all remaining arguments for *varargs.
    if fn_spec.varargs is not None:
      varargs, remaining_args = remaining_args, []
    else:
      varargs = []

    for index, value in enumerate(varargs):
      varargs[index] = _ParseValue(value, None, None, metadata)

    varargs = parsed_args + varargs
    remaining_args += remaining_kwargs

    consumed_args = args[:len(args) - len(remaining_args)]

View on GitHub (pinned to 716bbc23d7)

Solutions

1. Remove or correct the unexpected flag name
2. Add **kwargs to the function signature to absorb extra flags
3. Check --help output for the accepted flags

Example fix

// before
def run(speed, *, verbose=None): ...  # invoked: run --spead=5
// after
def run(speed, *, verbose=None, **kwargs): ...  # or fix flag spelling: run --speed=5

extra = set(supplied_flags) - set(inspect.signature(fn).parameters)
spec = inspect.signature(fn)
accepts_kw = any(p.kind == p.VAR_KEYWORD for p in spec.parameters.values())
if extra and not accepts_kw:
    raise TypeError(f'unknown flags: {extra}')

def flags_accepted(fn, flags) -> bool:
    params = inspect.signature(fn).parameters
    return not flags or any(p.kind == p.VAR_KEYWORD for p in params.values()) or set(flags) <= set(params)

try:
    fire.Fire(component)
except fire.core.FireError as e:
    if 'Unexpected kwargs present' in str(e):
        print('unknown flag; check -- --help', file=sys.stderr)
        sys.exit(2)
    raise

When it happens

Trigger: Calling fn(a, b, *, c=None) with an extra --d=3 flag; passing a misspelled keyword flag (mytool run --tyep=fast); passing flags meant for another command in the chain.

Common situations: Typos in flag names; changed function signatures after removing/renaming keyword-only params; scripts caching old flag sets.

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/37b990c7f8dd12d1. Report an issue: GitHub.