# `Cucumber.AmbiguousStepError`
[🔗](https://github.com/huddlz-hq/cucumber/blob/main/lib/cucumber/ambiguous_step_error.ex#L1)

Exception raised when a step's text matches more than one step definition.

Cucumber cannot know which definition the author intended, so the scenario
fails with this error listing every matching pattern and where each is
defined. Ambiguity is a property of a concrete step text at runtime — two
patterns may overlap for one input but not another — so this is detected
during step resolution, not at load time.

This is a distinct exception type (rather than a `Cucumber.StepError`) so
downstream features can treat it specially — e.g. retry logic must never
retry an ambiguous step, and Cucumber Messages report it as AMBIGUOUS
rather than FAILED.

# `match`

```elixir
@type match() :: {pattern_source :: String.t(), module(), metadata :: map()}
```

# `t`

```elixir
@type t() :: %Cucumber.AmbiguousStepError{
  __exception__: term(),
  feature_file: String.t() | nil,
  matches: [match()],
  message: String.t(),
  scenario_name: String.t() | nil,
  step: Gherkin.Step.t() | nil
}
```

# `new`

```elixir
@spec new(Gherkin.Step.t(), [match()], String.t(), String.t()) :: t()
```

Builds the error for a step that matched several definitions.

`matches` is a list of `{pattern_source, module, metadata}` tuples, where
metadata carries the definition's `:file` and `:line`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*