Understanding the Selenium error "Modal Dialog Present"

So your Cucumber feature sometimes dies with this exception:

Modal Dialog Present (Selenium::WebDriver::Error::UnhandledAlertError)

As a seasoned Selenium vetaran you are used to misleading error messages. Hence you might be surprised that the reason for this particular error is that there is actually a modal dialog present and preventing Selenium from executing commands like click or page.have_css?.

How your code triggers this issue

The reason why a dialog is shown is somewhat fucked up. It often happens like this:

@javascript
Scenario: First scenario
  When I am on a page
  And I trigger an AJAX request that shows an alert in case of an error
  
@javascript
Scenario: Second scenario
  When I am on another page

If your PC is fast enough, the "When I am on another page" from the second scenario can interrupt an incomplete AJAX request from the first scenario. This triggers the error alert callback you so helpfully registered in your Javascript. Because Selenium keeps your browser window around between scenarios, your second scenario now fails.

How to solve this

Make sure your AJAX requests always finish before your scenario ends.