{"record":{"id":"2b19d932ab5ebf46","repo":"teamcapybara/capybara","slug":"capybara-requires-puma-version-3-8-0-or-higher","errorCode":null,"errorMessage":"Capybara requires `puma` version 3.8.0 or higher, please upgrade `puma` or register and specify your own server block","messagePattern":"Capybara requires `puma` version 3\\.8\\.0 or higher, please upgrade `puma` or register and specify your own server block","errorType":"exception","errorClass":"LoadError","httpStatus":null,"severity":"critical","filePath":"lib/capybara/registrations/servers.rb","lineNumber":34,"sourceCode":"  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)\n\n  logger = (defined?(Puma::LogWriter) ? Puma::LogWriter : Puma::Events).then do |cls|\n    conf.options[:Silent] ? cls.strings : cls.stdio\n  end\n  conf.options[:log_writer] = logger","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/registrations/servers.rb#L16-L52","documentation":"Puma is installed but too old: Capybara's :puma server block builds and runs the Puma server itself (to avoid signal-handler side effects of the rack handler's #run), which requires the handler to expose a .config class method. Rack::Handler::Puma gained config in puma 3.8.0; older versions fail the respond_to?(:config) check and raise LoadError.","triggerScenarios":"Gemfile.lock pins puma to < 3.8.0 (e.g. puma (~> 2.16) on a legacy Rails app) or a system/global old puma shadows the bundled one; the first spec that boots the Capybara server raises this.","commonSituations":"Legacy applications with old puma constraints; transitive gem pins preventing an upgrade; deploying test suite into an image that ships its own puma; upgrading Capybara without revisiting the puma constraint.","solutions":["Upgrade puma to at least 3.8.0 (puma ~> 5.0 or ~> 6.0 recommended) and run bundle update puma.","Check what is pinning it: bundle info puma and look at Gemfile.lock dependencies that constrain the version.","If an upgrade is impossible, use a different server: Capybara.server = :webrick (add the webrick gem on Ruby 3+).","Confirm the runtime version Capybara sees: require 'puma'; puts Puma::Const::PUMA_VERSION in the test boot."],"exampleFix":"# before (Gemfile)\ngem 'puma', '~> 2.16'\n\n# after (Gemfile)\ngem 'puma', '~> 6.0'","handlingStrategy":"validation","validationCode":"require 'puma'\nraise LoadError, 'Capybara needs puma >= 3.8.0' if Gem::Version.new(Puma::Const::PUMA_VERSION) < Gem::Version.new('3.8.0')","typeGuard":"def puma_config_capable?\n  handler = defined?(Rackup::Handler::Puma) ? Rackup::Handler::Puma : Rack::Handler::Puma\n  handler.respond_to?(:config)\nend","tryCatchPattern":null,"preventionTips":["Constrain puma in the Gemfile (gem 'puma', '>= 3.8') so bundler fails at install time, not mid-spec-run.","After environment changes, verify with `bundle exec ruby -e \"puts Puma::Const::PUMA_VERSION\"` in CI."],"tags":["ruby","capybara","puma","server","version-compatibility"],"backgroundTag":"gem-version-incompatible","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}