teamcapybara/capybara · error · CapybaraError

Your application server raised an error - It has been raised

Error message

Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true

What it means

When the application under test raises while serving a request, Capybara's test server stores the exception; on the next driver interaction raise_server_error! re-raises it in the test thread. This CapybaraError is attached as the exception cause to explain that Capybara.raise_server_errors == true promoted the app error into the test run.

Source

Thrown at lib/capybara/session.rb:164

    #
    def quit
      @driver.quit if @driver.respond_to? :quit
      @document = @driver = nil
      @touched = false
      @server&.reset_error!
    end

    ##
    #
    # Raise errors encountered in the server.
    #
    def raise_server_error!
      return unless @server&.error

      # Force an explanation for the error being raised as the exception cause
      begin
        if config.raise_server_errors
          raise CapybaraError, 'Your application server raised an error - It has been raised in your test code because Capybara.raise_server_errors == true'
        end
      rescue CapybaraError => capy_error # rubocop:disable Naming/RescuedExceptionsVariableName
        raise @server.error, cause: capy_error
      ensure
        @server.reset_error!
      end
    end

    ##
    #
    # Returns a hash of response headers. Not supported by all drivers (e.g. Selenium).
    #
    # @return [Hash<String, String>] A hash of response headers.
    #
    def response_headers
      driver.response_headers
    end

View on GitHub (pinned to 15b5fdb76e)

Solutions

1. Inspect the cause: rescue => e; puts e.cause.full_message - the real app exception and backtrace are there; then fix the app code
2. Reproduce outside Capybara (request spec, curl against the booted server port, test.log) if the cause is unclear
3. When visiting intentionally-broken endpoints, narrow Capybara.server_errors to specific classes or temporarily set Capybara.raise_server_errors = false in an around-hook - debug only, since it hides real failures
4. Check the app's own log for the original stack trace

Example fix

# before
it 'shows checkout' do
  visit '/checkout' # raises wrapped CapybaraError, real cause buried
end

# after (surface the real app error while debugging)
it 'shows checkout' do
  visit '/checkout'
rescue Capybara::CapybaraError => e
  raise e.cause if e.cause # re-raise the actual app exception
  raise
end

begin
  visit '/checkout'
  click_button 'Pay'
rescue Capybara::CapybaraError => e
  # e.cause holds the real exception raised by your app
  AppErrorReporter.notify(e.cause) if e.cause
  raise
end

When it happens

Trigger: A controller/model exception during visit/click (app returns 500) followed by any further Capybara call; exceptions of classes listed in Capybara.server_errors (default StandardError) raised by middleware or the app itself.

Common situations: Genuine app bugs surfaced by feature specs; environment-specific failures (missing env var, migration mismatch) only raising in test env; specs that intentionally visit broken endpoints; flaky uniqueness/validation errors under parallel tests.

Related errors

• The second parameter to Session::new should be a rack app if

AI-assisted analysis of teamcapybara/capybara@15b5fdb76e (2026-08-21). Data as JSON: /api/errors/2c6d72a8e792b7de. Report an issue: GitHub.