teamcapybara/capybara · critical · LoadError

Capybara is unable to load `puma` for its server, please add

Error message

Capybara is unable to load `puma` for its server, please add `puma` to your project or specify a different server via something like `Capybara.server = :webrick`.

What it means

Capybara's default registered server is :puma, and booting it requires being able to require 'rack/handler/puma' (or the newer rackup handler). When both requires fail, Capybara raises LoadError with instructions: either add the puma gem or pick another server such as Capybara.server = :webrick. This happens at server boot time, i.e. on the first visit against an app-backed session.

Source

Thrown at lib/capybara/registrations/servers.rb:29

  rescue LoadError
    # Rack 3 separated out the webrick handle - no way test currently in Capybaras automated
    # tests due to Sinatra not yet supporting Rack 3 - experimental
    require 'rackup/handler/webrick'
    Rackup
  end
  options = { Host: host, Port: port, AccessLog: [], Logger: WEBrick::Log.new(nil, 0) }.merge(options)
  base_class::Handler::WEBrick.run(app, **options)
end

Capybara.register_server :puma do |app, port, host, **options| # rubocop:disable Metrics/BlockLength
  begin
    require 'rackup'
  rescue LoadError # rubocop:disable Lint/SuppressedException
  end
  begin
    require 'rack/handler/puma'
  rescue LoadError
    raise LoadError, 'Capybara is unable to load `puma` for its server, please add `puma` to your project or specify a different server via something like `Capybara.server = :webrick`.'
  end
  puma_rack_handler = defined?(Rackup::Handler::Puma) ? Rackup::Handler::Puma : Rack::Handler::Puma

  unless puma_rack_handler.respond_to?(:config)
    raise LoadError, 'Capybara requires `puma` version 3.8.0 or higher, please upgrade `puma` or register and specify your own server block'
  end

  # If we just run the Puma Rack handler it installs signal handlers which prevent us from being able to interrupt tests.
  # Therefore construct and run the Server instance ourselves.
  # puma_rack_handler.run(app, { Host: host, Port: port, Threads: "0:4", workers: 0, daemon: false }.merge(options))
  default_options = { Host: host, Port: port, Threads: '0:4', workers: 0, daemon: false }
  options = default_options.merge(options)

  conf = puma_rack_handler.config(app, options)
  conf.clamp

  puma_ver = Gem::Version.new(Puma::Const::PUMA_VERSION)
  require_relative 'patches/puma_ssl' if Gem::Requirement.new('>=4.0.0', '< 4.1.0').satisfied_by?(puma_ver)

View on GitHub (pinned to 15b5fdb76e)

Solutions

1. Add puma to the Gemfile (gem 'puma') in the group your test environment installs, then bundle install.
2. Or switch servers: Capybara.server = :webrick, adding gem 'webrick' on Ruby 3.0+.
3. Or register your own server block (Capybara.register_server(:my_server) { |app, port, host, **opts| ... }) and set Capybara.server = :my_server.
4. Verify the require works in the CI bundle: bundle exec ruby -e "require 'rack/handler/puma'" and treat a failure as an environment problem, not a spec problem.

Example fix

# before (Gemfile has no puma)
# -> LoadError on first visit

# after
# Gemfile
gem 'puma', '~> 6.0'

begin
  require 'rack/handler/puma'
rescue LoadError
  Capybara.server = :webrick # ensure gem 'webrick' on Ruby 3+
end

begin
  Capybara.server = :puma # default; boots lazily on first visit
rescue LoadError
  Capybara.server = :webrick
  retry # next visit attempt
end

When it happens

Trigger: Running feature/system specs with the default configuration in a project whose Gemfile lacks puma (or excludes it from the test/default groups); visiting a page with Capybara.server left at the default :puma.

Common situations: Minimal Rack/Sinatra test setups; JRuby or container images trimmed of puma; CI bundles with 'without development test' stripping the group; Ruby >= 3.0 projects where the old webrick fallback is also gone unless the gem is added.

Related errors

• Capybara requires `puma` version 3.8.0 or higher, please upg
• Invalid option #{match.inspect} for :match, should be one of
• Invalid option(s) #{invalid_names}, should be one of #{valid
• #{@type} is not a valid type for a text query
• redirected more than #{driver.redirect_limit} times, check f

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