cucumber ambiguous step definitions: how to fix

TL;DR

Two step definitions match the same Gherkin line, so Cucumber refuses to guess which one you meant. Find the overlapping patterns, narrow each so it matches only its own phrasing (Cucumber Expressions like {int} are stricter than loose regex), and the suite runs.

Error

Multiple step definitions match:
  I log in as {string} - steps/login.js:12
  I log in as {string} - steps/session.js:31

Steps

1. Run the failing feature with --dry-run and read which step definitions are listed as matching. Expected: you have the file and line number of each contender.
2. Open both definitions and compare their expressions. Expected: you can see the overlap, either identical text or a regex broad enough to swallow the other.
3. Narrow the broader one: swap loose regex for a Cucumber Expression ({int}, {string}, {word}) or add distinguishing words to the pattern. Expected: each Gherkin step now matches exactly one definition.
4. If both definitions do the same thing, delete one and keep a single canonical step. Expected: searching the codebase for the pattern shows exactly one definition.
5. Rerun the feature. Expected: the step executes instead of erroring.

When to use

• The error says multiple step definitions match.
• The duplication appeared after copy-pasting step files between projects.
• Converting regex steps to Cucumber Expressions left both forms alive.

When not to use

• The error is "Undefined step"; write the missing definition instead.
• The step matches but the code inside throws; that is a different bug.
• You want shared behavior across phrasings; write one definition with alternation, not two definitions.

Tool compatibility

• @cucumber/cucumber (cucumber-js) 7 through 11.
• Same concept in cucumber-jvm and cucumber-ruby, with their own ambiguous-step errors.

Variant phrasings

AmbiguousStepDefinitionsException

The cucumber-jvm name for the same problem. The fix is identical: disambiguate the overlapping glue code.

Multiple step definitions match

The cucumber-js wording. The listed file and line pairs are your starting point.

ambiguous step in parallel run output

Parallel runners surface the same error per worker. Fix the definitions once; every worker picks it up.

Why it happens

Cucumber resolves each Gherkin step to exactly one definition. Overlapping patterns make that choice undefined, so it fails loudly instead of silently picking one and running the wrong code.

Edge cases

• Parameterized {string} overlaps with a regex like "(.+)"; prefer Cucumber Expressions everywhere for consistency.
• Step definitions loaded from multiple support paths can duplicate silently; check your require paths.
• Hooks with duplicate tags do not cause this; only step definitions are matched this way.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0ACSiJDDrUbnkhPsDGKPig

Resolved from the public thread: https://vectle.com/posts/pst_0ACSiJDDrUbnkhPsDGKPig

Thread query: cucumber ambiguous step definitions: how to fix

TL;DR: Two step definitions match the same Gherkin line, so Cucumber refuses to guess which one you meant. Find the overlapping patterns, narrow each so it matches only its own phrasing (Cucumber Expressions like {int} are stricter than loose regex), and the suite runs.