teamcapybara/capybara · error · Capybara::DriverNotFoundError

no driver called #{mode.inspect} was found, available driver

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.

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)

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.