All jobs

Fix "cannot load such file -- webrick (LoadError)" on Ruby 3

Yes. An agent finds each script that requires webrick, declares the gem where the project keeps its dependencies, starts the server, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Ruby 3.0 stopped shipping WEBrick as a default gem. A script that says require 'webrick' and never declared the gem, because it never had to, now stops with cannot load such file -- webrick (LoadError). Ruby 3.3 prints a hint above the error: webrick is not part of the default gems starting from Ruby 3.0.0. Install webrick from RubyGems. ticky/wayback-classic shows how the problem hides. The site is a set of CGI scripts under cgi-bin/, and its README says the root directory has "no dependencies other than the Ruby standard library". That was true of bin/dev-server when it was written. The script is 17 lines that start a WEBrick::HTTPServer on port 8000 with the repository as its document root, and line 4 is require 'webrick'.

The agent first works out why nothing caught it. The tests live in tests/ with their own Gemfile (capybara, minitest, rack, rake, vcr and webmock) and a Rakefile. capybara_test_case.rb loads each CGI script as a Ruby module behind a small Rack application, so the suite never starts bin/dev-server. On Ruby 3.3, bundle exec rake in tests/ passes all 32 tests, and .github/workflows/ruby.yml runs exactly that command. A green suite and a dev server that cannot start sit side by side. So the agent runs ruby bin/dev-server itself, on a Ruby installed without the gem, and keeps the LoadError that points at bin/dev-server:4.

Then it decides where the dependency belongs, which is the real question in a repository laid out like this one. gem install webrick fixes one machine and documents nothing. A Gemfile at the top level would sit inside the directory the site is served from. The repository already has one place for development-only gems, tests/Gemfile, so the agent adds gem 'webrick' there, runs bundle lock so that tests/Gemfile.lock records the version, and changes the README's Development section to start the server with BUNDLE_GEMFILE=tests/Gemfile bundle exec ruby bin/dev-server. It starts the server that way, requests / and one path under /cgi-bin/, and records both status codes.

It also writes down what it notices beside the fix without changing it. bin/dev-server passes CGIInterpreter: '/usr/bin/ruby -Eutf-8:utf-8', so the CGI scripts run under the system Ruby whichever Ruby started the server. On a machine with two Rubies, the page under test may not be running on the version the developer thinks. And Debian 12 installs a ruby-webrick package together with ruby, which is why the same script starts on one machine and fails on another that uses a version manager. Both go into the pull request description as notes for the maintainer.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Starting this project's development server on Ruby 3 fails with \"cannot load such file -- webrick (LoadError)\". Fix it. Find every file that requires webrick or names it as a Rack handler, including scripts under bin/, Rakefiles and rackup files. Reproduce the error first on a Ruby that does not have the webrick gem installed, and keep the output with the file and line. Find out why the test suite and CI did not catch it. Then declare the gem where this project already declares its dependencies: the gemspec for a gem, the Gemfile for an application, or the development or test manifest when only a development script needs it. Regenerate the lockfile with Bundler instead of editing it by hand, and update any README command that would no longer work. Do not add a Gemfile to a directory that is served to the public, and do not switch to another web server. Start the server the documented way, request the root path and one dynamic path, and report the status codes. Run the existing tests on the same Ruby. List anything else you notice that depends on which Ruby is installed, without changing it. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request with three small changes: one gem 'webrick' line in the manifest that holds the project's development dependencies, the regenerated lockfile, and README instructions that match. The description shows the LoadError from before the change with its file and line, the server's startup lines and the two status codes from after it, and the result of the existing test suite on the same Ruby.

The description is plain about what the change does not touch. In a project like wayback-classic the README tells operators to deploy the scripts as ordinary CGI and never to use bin/dev-server in production, so nothing that serves visitors changes. The lockfile diff should add WEBrick and nothing else, and the description says so, because a lockfile regenerated by a newer Bundler can move other entries.

A reviewer checks two things before merging: that the documented command starts the server on their own machine, and that the manifest the agent chose is the one they want. Some maintainers would rather keep a development script free of Bundler and put a bundler/inline block at the top of the script. The description names that alternative so the choice is a one-line reply.

Run it on every repository before a Ruby upgrade

This error appears the day a team moves a service, a CI image or a laptop from Ruby 2.7 to 3.x, and it appears once per repository. Start one run per repository before the upgrade instead of waiting for each one to break. A short script reads the repositories your GitHub App installation covers from GET /o/{org}/github and posts this request once for each, changing only the resources URL.

To make the script safe to run again, send a request_id with each start, a UUID v5 made from the repository name and the target Ruby version: the same id with the same body returns the run it first started. A key runs at most max_concurrent runs at once, 4 by default, and the rest wait as queued and start as slots free up, so the script needs no pacing of its own. Give the key a webhook_url and every run it starts posts run.completed or run.failed there when its turn finishes.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

Whether this error shows up depends on what happens to be installed. A laptop that has run gem install webrick once, or a distribution that packages the gem beside Ruby, starts the server without complaint, and the person who would fix it never sees it. Each run gets its own sandbox, where the agent installs a Ruby that has only its default gems. The failure is reproduced there on purpose, and the transcript keeps the command and its output.

The same holds for the proof after the fix. The session's transcript has every command the agent ran, ruby bin/dev-server and bundle exec rake among them, each with its output, so a reviewer reads the server's own log lines instead of a sentence saying it works. And since each run has its own machine, many repositories can be checked side by side, up to the key's concurrency limit, without waiting on anyone's attention.

Frequently asked questions

Why did require 'webrick' stop working?

WEBrick used to come with Ruby as a default gem. Since Ruby 3.0 it is an ordinary gem that has to be installed and, under Bundler, listed in the Gemfile. Code that relied on it being present needs the dependency declared.

Is running gem install webrick enough?

It makes the error go away on that machine. The next clone, the CI image and any command run through bundle exec will still fail, because Bundler only loads gems the Gemfile names. Declaring the gem in the project is the fix that travels with the code.

Is this the same error jekyll serve gives on Ruby 3?

It has the same cause. Jekyll's local server uses WEBrick, and Jekyll's quickstart tells Ruby 3 users to run bundle add webrick in the site's directory. Pointed at a Jekyll site, the agent makes that change in the site's Gemfile and proves it by starting bundle exec jekyll serve.

Will the agent replace WEBrick with Puma or another server?

No. The request tells it not to switch servers. A development script that worked for years needs its dependency declared; choosing a different server is a separate decision with its own trade-offs, and the agent leaves it to you.

Does this change how my site is deployed?

Not when WEBrick is only the development server. The agent says which files require it and whether any of them is on a production path. If one is, the description says so and the gem goes into the main manifest instead of a development one.

More jobs like this: Fix a bug from an alert

Keep reading