teamcapybara/capybara · error · Capybara::DriverNotFoundError

no driver called # was found, available drivers: #

Error message

no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}

What it means

Sessions resolve their driver lazily; when the requested mode symbol is not registered in Capybara.drivers, Capybara::DriverNotFoundError is raised with the list of registered driver names. The message exists to catch typos and unregistered third-party drivers.

Solutions

  1. Print Capybara.drivers.names and fix the symbol to a registered driver (built-ins include :rack_test, :selenium, :selenium_headless)
  2. Register the driver before first use: Capybara.register_driver(:headless_chrome) { |app| ... } in a file loaded by spec_helper/rails_helper
  3. If a gem provides the driver (cuprite, apparition), require it and follow its registration docs; verify the gem is in the CI bundle

Example fix

# before
Capybara.default_driver = :headless_chrome # never registered

# after
Capybara.register_driver :headless_chrome do |app|
  Capybara::Selenium::Driver.new(app, browser: :chrome,
    options: Selenium::WebDriver::Chrome::Options.new(args: ['--headless=new']))
end
Capybara.default_driver = :headless_chrome
Defensive patterns

Strategy: validation

Validate before calling

def driver_registered?(name)
  Capybara.drivers.names.include?(name)
end

raise Capybara::DriverNotFoundError,
      "#{Capybara.default_driver} not registered. Have: #{Capybara.drivers.names.join(', ')}" unless driver_registered?(Capybara.default_driver)

Try / catch

begin
  page.driver
rescue Capybara::DriverNotFoundError => e
  warn e.message # lists available drivers; fix the symbol or register it
  raise
end

Prevention

When it happens

Trigger: Capybara::Session.new(:selenium_firfox, app) (typo); Capybara.default_driver = :poltergeist after removing the poltergeist gem; using :cuprite/:apparition/:webkit without requiring the gem that registers it; registering the driver after the session/driver was first accessed.

Common situations: Replacing an abandoned driver (poltergeist/capybara-webkit) with cuprite while specs still name the old symbol; driver registration code in a file CI does not load; spring/forked runners skipping registration; typos in env-driven driver selection.

Related errors

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

Appendix: source

Thrown at lib/capybara/session.rb:104

      @app = app
      if block_given?
        raise 'A configuration block is only accepted when Capybara.threadsafe == true' unless Capybara.threadsafe

        yield config
      end
      @server = if config.run_server && @app && driver.needs_server?
        server_options = { port: config.server_port, host: config.server_host, reportable_errors: config.server_errors }
        server_options[:extra_middleware] = [Capybara::Server::AnimationDisabler] if config.disable_animation
        Capybara::Server.new(@app, **server_options).boot
      end
      @touched = false
    end

    def driver
      @driver ||= begin
        unless Capybara.drivers[mode]
          other_drivers = Capybara.drivers.names.map(&:inspect)
          raise Capybara::DriverNotFoundError, "no driver called #{mode.inspect} was found, available drivers: #{other_drivers.join(', ')}"
        end
        driver = Capybara.drivers[mode].call(app)
        driver.session = self if driver.respond_to?(:session=)
        driver
      end
    end

    ##
    #
    # Reset the session (i.e. remove cookies and navigate to blank page).
    #
    # This method does not:
    #
    # * accept modal dialogs if they are present (Selenium driver now does, others may not)
    # * clear browser cache/HTML 5 local storage/IndexedDB/Web SQL database/etc.
    # * modify state of the driver/underlying browser in any other way
    #
    # as doing so will result in performance downsides and it's not needed to do everything from the list above for most apps.

View on GitHub (pinned to 15b5fdb76e)