{"record":{"id":"acc6af80d303868d","repo":"teamcapybara/capybara","slug":"capybara-is-unable-to-load-puma-for-its-server","errorCode":null,"errorMessage":"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`.","messagePattern":"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`\\.","errorType":"exception","errorClass":"LoadError","httpStatus":null,"severity":"critical","filePath":"lib/capybara/registrations/servers.rb","lineNumber":29,"sourceCode":"  rescue LoadError\n    # Rack 3 separated out the webrick handle - no way test currently in Capybaras automated\n    # tests due to Sinatra not yet supporting Rack 3 - experimental\n    require 'rackup/handler/webrick'\n    Rackup\n  end\n  options = { Host: host, Port: port, AccessLog: [], Logger: WEBrick::Log.new(nil, 0) }.merge(options)\n  base_class::Handler::WEBrick.run(app, **options)\nend\n\nCapybara.register_server :puma do |app, port, host, **options| # rubocop:disable Metrics/BlockLength\n  begin\n    require 'rackup'\n  rescue LoadError # rubocop:disable Lint/SuppressedException\n  end\n  begin\n    require 'rack/handler/puma'\n  rescue LoadError\n    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`.'\n  end\n  puma_rack_handler = defined?(Rackup::Handler::Puma) ? Rackup::Handler::Puma : Rack::Handler::Puma\n\n  unless puma_rack_handler.respond_to?(:config)\n    raise LoadError, 'Capybara requires `puma` version 3.8.0 or higher, please upgrade `puma` or register and specify your own server block'\n  end\n\n  # If we just run the Puma Rack handler it installs signal handlers which prevent us from being able to interrupt tests.\n  # Therefore construct and run the Server instance ourselves.\n  # puma_rack_handler.run(app, { Host: host, Port: port, Threads: \"0:4\", workers: 0, daemon: false }.merge(options))\n  default_options = { Host: host, Port: port, Threads: '0:4', workers: 0, daemon: false }\n  options = default_options.merge(options)\n\n  conf = puma_rack_handler.config(app, options)\n  conf.clamp\n\n  puma_ver = Gem::Version.new(Puma::Const::PUMA_VERSION)\n  require_relative 'patches/puma_ssl' if Gem::Requirement.new('>=4.0.0', '< 4.1.0').satisfied_by?(puma_ver)","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/registrations/servers.rb#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add puma to the Gemfile (gem 'puma') in the group your test environment installs, then bundle install.","Or switch servers: Capybara.server = :webrick, adding gem 'webrick' on Ruby 3.0+.","Or register your own server block (Capybara.register_server(:my_server) { |app, port, host, **opts| ... }) and set Capybara.server = :my_server.","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."],"exampleFix":"# before (Gemfile has no puma)\n# -> LoadError on first visit\n\n# after\n# Gemfile\ngem 'puma', '~> 6.0'","handlingStrategy":"fallback","validationCode":"begin\n  require 'rack/handler/puma'\nrescue LoadError\n  Capybara.server = :webrick # ensure gem 'webrick' on Ruby 3+\nend","typeGuard":null,"tryCatchPattern":"begin\n  Capybara.server = :puma # default; boots lazily on first visit\nrescue LoadError\n  Capybara.server = :webrick\n  retry # next visit attempt\nend","preventionTips":["Declare puma (or webrick plus Capybara.server = :webrick) explicitly in the Gemfile group CI installs.","Smoke-test server boot in CI with a one-line spec that visits the root path before the full suite."],"tags":["ruby","capybara","puma","server","gemfile","setup"],"backgroundTag":"missing-gem-dependency","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}