Diagnosing Ruby Keyword Argument ArgumentError: Missing or Unknown Keywords

Recognizable condition

When invoking a Ruby method that expects keyword arguments, you see an ArgumentError such as:

• missing keyword: :foo (ArgumentError)
• unknown keyword: :bar (ArgumentError)

Cause / diagnostic table

#	Possible cause	What to look for
1	Method defines required keyword arguments without defaults	Signature like def meth(a:, b:)
2	Caller passes positional arguments or mismatched keyword names	Call looks like meth(1, 2) or meth(a: 1, baz: 2)
3	Caller supplies extra keywords not accepted by the method	Hash includes keys beyond those in the method signature
4	Caller omits a required keyword	Missing key such as :b when b: is required
5	Caller uses string keys instead of symbols (Ruby 2.7+ treats them as separate unless **opts)	Call like meth('a' => 1)

Ordered checks

1. Verify the method signature

   Run method(:method_name).parameters in a console or add p method(:method_name).parameters to the script to see expected keyword parameters (e.g., [[:key, :a]], [[:key, :b]]).

2. Inspect the call site

   Locate the invocation and print the argument hash before the call: puts args.inspect where args is the hash being passed.

3. Ensure all required keywords are present

   Compare the set of required keys from method(:method_name).parameters (those without a default) with the keys in the call hash.

4. Ensure no extra keys

   If the method does not accept **opts, any key not listed in the signature will trigger unknown keyword. Remove or rename them.

5. Confirm keys are symbols

   Ruby 2.7+ treats string keys as separate unless the method uses **opts. Convert string keys to symbols (hash.transform_keys(&:to_sym)) or adjust the method to accept **opts and map internally.

Fixes tied to findings

• Missing required keyword – Add the key with an appropriate value, e.g., meth(a: 1, b: 2).
• Mismatched or extra keyword – Rename keys to match the method’s expected symbols or delete the extraneous ones.
• Omitting a required keyword – Supply the missing keyword; if the value is optional, consider adding a default in the method definition: def meth(a:, b: 1).
• Using string keys – Convert the hash: meth(hash.transform_keys(&:to_sym)) or change the method to accept **opts and map symbols inside.
• Forbidding extra keywords (Ruby 3.0+) – Change the method signature to def meth(a:, b: nil, **nil) to raise on unexpected keys.
• Allowing extra keywords – Use def meth(a:, b:, **opts) and process opts as needed.

Escalation criteria

1. If the ArgumentError persists after verifying the keyword hash, check for method redefinitions via refinements, alias_method_chain, or monkey‑patches that may have altered the signature.
2. Confirm gem versions; a dependency might have introduced a newer version of the method with a different signature.
3. If the issue remains unresolved, isolate a minimal reproducer (method definition + call) and open an issue in the relevant repository, including Ruby version (ruby --version) and the full error message.