What the agent does
Ruby 3.1 moved net-smtp, net-imap and net-pop from default gems to bundled gems. They are still installed with Ruby, so ruby -e 'require "net/smtp"' works at a plain prompt, but under bundle exec only the gems in the Gemfile are loadable, and require "net/smtp" fails with cannot load such file -- net/smtp (LoadError). The call usually is not yours: mail 2.6.3's lib/mail.rb line 8 requires it, so the error names the mail gem's file, and mail 2.8 is the first release whose gemspec declares net-smtp, net-imap and net-pop as runtime dependencies so Bundler pulls them in.
In a Sinatra app like agerdes/voicemailer.rb, the Gemfile lists sinatra, twilio-ruby, mail and dotenv with minitest and rack-test for tests, and the lockfile pins mail 2.6.3 with mime-types 2.6.1, sinatra 1.4.6, rack 1.6.4 and twilio-ruby 4.2.1, ending with BUNDLED WITH 1.10.6. app.rb requires twilio-ruby, mail and sinatra; lib/message.rb builds a Mail.new block that checks options[:recording_path].blank? on line 16 before attaching a recording; and the Rakefile runs test/*_test.rb through Rake::TestTask, though rake itself is not in the Gemfile. The README asks for Ruby 2.3.0 or newer.
The agent reproduces it on the lockfile first, and the lockfile fights back: bundle install reads BUNDLED WITH 1.10.6, installs Bundler 1.10.6 and crashes on Ruby 3.1 with undefined method 'inflate' for Gem:Module. With that block removed the current Bundler installs the 14 locked gems, and bundle exec ruby -e 'require "mail"' fails at mail-2.6.3/lib/mail.rb:8 with the LoadError, while the same require outside Bundler loads net-smtp 0.3.1. It then tries the smallest change, adding gem "net-smtp" beside mail 2.6.3: the install succeeds, and the require moves one gem over to mime-types 2.6.1, whose logger.rb line 26 uses _1 as a block parameter name that Ruby 3.1 reserves, so it fails with a SyntaxError. The old mail release cannot be kept.
With gem "mail", "~> 2.8", bundle install resolves mail 2.9.1 and brings net-smtp 0.5.2, net-imap 0.5.15, net-pop 0.1.2, net-protocol, mini_mime 1.1.5, logger and date 3.6.0, which needs a C compiler for its extension; sinatra, rack and twilio-ruby stay at their pins. The require passes. The test suite, with rake added to the Gemfile, then reports 32 runs with 11 errors, all NoMethodError: undefined method 'blank?' at lib/message.rb:16: mail 2.6.3 shipped core extensions that put blank? on Object, NilClass and String, and mail 2.9.1 keeps only Mail::Utilities.blank?. The agent replaces the call with a nil-or-empty check in the app's own code, reruns the suite and lists the remaining warnings from the 2015 sinatra and twilio-ruby pins without changing them.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This Ruby app fails under bundle exec with cannot load such file -- net/smtp (LoadError). On the newest stable Ruby, run bundle install from the lockfile and report what happens, including any Bundler version the lockfile's BUNDLED WITH line forces; then show the LoadError under bundle exec and the same require succeeding outside Bundler, naming the gem and line that requires net/smtp. Try adding the net-smtp gem alone and report the next failure, if any. Then raise the mail gem to a release whose gemspec depends on net-smtp, keeping every other gem at its locked version, and show the lockfile diff. Add rake to the Gemfile if the Rakefile needs it, run the test suite, and fix only what the mail upgrade broke in the app's own code, such as a core extension the old mail gem used to add; do not upgrade sinatra or twilio-ruby in this change. List deprecation warnings from the other pinned gems without acting on them. Open a pull request with the install transcript, the lockfile diff and both test runs.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 that changes the Gemfile, the lockfile and the one file in lib that used the removed core extension. The description opens with the install transcript on the current Ruby: the Bundler crash the BUNDLED WITH line caused, the LoadError with the gem and line that raised it, and the plain-Ruby require that shows net-smtp is installed but invisible to Bundler. The lockfile diff follows, with mail and its new dependencies added and nothing else moved.
The two test runs sit side by side: the first after the upgrade, with every error pointing at the same line, and the second after the fix in the app's code. The session's record keeps every bundle and rake command and the warnings the older pins print.
Before merging, a reviewer checks that the replacement for blank? treats nil and an empty string the way the old extension did, that the deployment image has the compiler the date gem's extension needs, and whether the sinatra and twilio-ruby pins the pull request left in place are due their own upgrade.
Run it on every Ruby version bump in CI
The error appears the first time the app runs on Ruby 3.1 or later: a CI image bump, a new Dockerfile base or a developer's fresh machine. When that job fails, a handler on your server reads the failure, and sends this request with POST /o/{org}/sessions with the repository in resources and the failing command's output appended to input. Give it a request_id that is a UUID v5 of the CI run id, so a retried delivery returns the run that already started instead of opening a second pull request.
A company moving several small Ruby services at once starts one run per repository from a script, one request each with that repository in resources, and merges the ones whose suites come back green.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The one-line error hides three problems: a lockfile that pins a Bundler that cannot run, a gem that requires a module Bundler will not load, and a dependency of the old gem that does not parse on the new Ruby. Finding that order takes a Ruby you may not have installed, a compiler for a native extension and several install attempts. In a Rush sandbox the agent installs the Ruby, runs each attempt and keeps the transcript, and the machine is gone when the run ends.
What comes back is a record, not a summary: the LoadError with its file and line, the lockfile diff and both test runs. A team with a handful of Sinatra services on old pins starts one run per repository with the same request, up to the key's max_concurrent limit at once, and the rest queue.
Frequently asked questions
Why does require 'net/smtp' work in irb but not under bundle exec?
Because on Ruby 3.1 net-smtp is a bundled gem, installed with Ruby but not part of the standard library's load path. Bundler restricts loadable gems to the Gemfile and its lockfile, so a gem nobody declared is invisible there. Declaring it, or depending on a mail release that declares it, is the fix.
Can I just add gem 'net-smtp' and keep mail 2.6?
In the example, no. The install succeeds, but mail 2.6.3's dependency mime-types 2.6.1 uses _1 as a block parameter, which Ruby 3.1 reserves, so the require fails on the next gem with a SyntaxError. mail 2.8 and later depend on mini_mime instead and declare net-smtp themselves.
What did the mail upgrade break?
The app called blank? on a string, a method mail 2.6.3 added to Object, NilClass and String through its core extensions. mail 2.9.1 keeps only Mail::Utilities.blank?, so every test that built a message failed on that line. The agent replaces it with a nil-or-empty check in the app's code rather than reaching into the gem.
Why did bundle install crash before any of this?
The lockfile ends with BUNDLED WITH 1.10.6, and Bundler installs and runs that version, which does not work on Ruby 3.1. Removing the block, or regenerating the lockfile with the current Bundler, is the first step, and the pull request shows it so the reviewer knows the lockfile was touched for that reason.