Last updated December 03, 2024

When deploying a Ruby application to Heroku, a version of Bundler will be installed and used to pull down the dependencies of your application.

To see the current Bundler version on Cedar-generation apps, see the Ruby Support page.

Version Configuration

The Bundler version that is used is not configurable on Cedar-generation apps, but is on Fir-generation apps. See Bundler Version Configuration for more info.

Why can’t the Bundler version be configured?

On Cedar-generation apps the version of bundler cannot be configured. Different versions of Bundler have different known bugs and slightly different behavior. The Bundler version on Heroku is carefully curated. A balance needs to be struck between supporting new Bundler features and stability. The work we put into curating the Bundler version ensures maximum stability, and avoids deprecation and notification cycles on Bundler as it changes, or as bugs are fixed or security issues are patched by Heroku.

The Ruby experience on Heroku is provided by the Heroku Ruby Buildpack. This is the tool that installs a version of Bundler and runs all the commands needed to get your application set up. The buildpack relies on publicly exposed internals of Bundler. It is tested and known to work against the currently specified version of Bundler. If you were to take a modern buildpack and use it with an older version of bundler, you would be likely to see unpredictable results.

Being aware of Bundler version changes

Changes to Bundler version on Cedar-generation apps will be announced on the Heroku changelog, and the Ruby Support page will be updated.

Bundler versions usually take a large amount of verification and validation and are released infrequently.

App not using the currently supported Bundler version?

If you see that a different version of Bundler is being used by your Cedar-generation apps application than is listed in the Ruby Support article, your application might be configured to use a main branch of the Ruby buildpack for deployments.

To check which buildpack is configured, use the heroku buildpacks command:

$ heroku buildpacks
=== hidden-temple-25627 Buildpack URL
https://github.com/heroku/heroku-buildpack-ruby.git

The example output shows that an unreleased version of the buildpack is being used. To switch to the supported version, set the buildpack as follows:

$ heroku buildpacks:set heroku/ruby
Buildpack set. Next release on hidden-temple-25627 will use heroku/ruby.
Run git push heroku master to create a new release using this buildpack.

You can verify that the new buildpack has been set by typing:

$ heroku buildpacks
=== hidden-temple-25627 Buildpack URL
heroku/ruby

Another reason your app might not be using the currently supported Bundler version is if it is configured to deploy using a different buildpack URL. This will happen if the BUILDPACK_URL config var is set.

$ heroku config:get BUILDPACK_URL
BUILDPACK_URL:                      https://github.com/heroku/heroku-buildpack-ruby.git

If you see any value, then you are using a custom buildpack. If this value is set to a “multi buildpack” such as https://github.com/heroku/heroku-buildpack-multi then you will need to check the .buildpacks file to see what buildpacks are used in deployment. If you are using this method of deployment we recommend that you instead follow the guidance in the Using Multiple Buildpacks for an App article.

The officially deployed Ruby buildpack will sometimes lag behind master for a few days.

Using an older version of Bundler

For Cedar-generation apps there is no way to specify a version of Bundler you want independently of the buildpack. You can, however, lock your app to a deployed version of the Ruby buildpack. When the Ruby buildpack is deployed a Ruby release is created on GitHub.

One of the most frequent problems for someone who has locked to an older buildpack version is when they encounter an error that prevents them from deploying. They find that the error was fixed in a more recent version of the buildpack, but in order to upgrade they must fix the original incompatibility. If this happens during a critical time then there is no emergency escape valve. They must spend time fixing their app. It is much better to stay up to date and not lock to a specific release version.

Heroku does not guarantee that locking to an older release will work forever. Platform changes may introduce incompatibilities with historical versions. If you encounter a new issue while deploying using a locked release you will be required to upgrade to the latest release before we can troubleshoot. No fixes will be backported to older releases. To mitigate these problems, only lock to a release for short periods of time.

To use a specific release version you can use the buildpack:set command and specify the release after a pound # in the URL. To lock to v224 you could run this command:

$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-ruby.git#v224

The next time you deploy you’ll get version v224 of the Ruby buildpack. You can see when a version of Bundler was deployed using the Heroku Ruby Buildpack changelog.

If your app is failing when using a version of Bundler then you can search for that version number to see when it was deployed. You can temporarily set your app to deploy using the version before it. For example, if your app is failing on version 1.11.2 search for “1.11.2” and see that v144 was the last deploy before this change was introduced so you can lock to v144.

Known upgrade issues

Bundler 2.4.22 and 2.5.6

On February 28, 2024 the Bundler version detection logic was upgraded so that applications that have BUNDLED WITH for 2.4.x and 2.5.x receive bundler 2.4.22 and 2.5.6 respectively. If your application begins to fail deployment with this change, first try deploying with the last prior version of Bundler by replacing BUNDLED WITH in your Gemfile.lock with these contents:

BUNDLED WITH
   2.3.25

After you’ve done that, commit the results to git and try deploying again.

$ git add Gemfile.lock
$ git commit -m "Bundler fix"

Ensure the version of bundler in your build output is 2.3.25. If the failure goes away, that might indicate a bug in Bundler. If the failure persists, that suggests that the problem is within your application and is unrelated to the Bundler version.

Bundler 2.4.22

Before Bundler 2.4, you could specify the ruby version in the Gemfile without being recorded in the Gemfile.lock. If your application unexpectedly reports that it’s now using a default version of Ruby, ensure that you have a Ruby declaration in your Gemfile. Then, run:

$ bundle update --ruby

Ensure there’s now a RUBY VERSION present in your Gemfile.lock. For example, if you’re using Ruby 3.2.2, you see the following towards the bottom of the file:

RUBY VERSION
   ruby 3.2.2p53

After you have a RUBY VERSION in your Gemfile.lock, commit it to git and try to deploy again:

$ git add Gemfile.lock
$ git commit -m "Add RUBY VERSION to Gemfile.lock"

Bundler 2.2.3+

An app’s Gemfile.lock that is generated with Bundler 2.2.3 locally may not work on Heroku unless the Linux platform is explicitly “locked”:

$ bundle lock --add-platform ruby
$ bundle lock --add-platform x86_64-linux
$ bundle install
$ git add . ; git commit -m "Bundler fix"

Bundler 2.0.2

See issues for 2.0.1. Please use the latest version of Ruby 2.6.x and 2.5.x.

Many people are hitting issue 4 (below), which is only triggered when a new Bundler version is released. It happens because of a bug in Rubygems, and can be fixed by upgrading to the latest version of 2.5.x and 2.6.x.

Bundler 2.0.1

1) If you are deploying with Ruby 2.6.0 then you’ll get an error when your dyno or a release phase command tries to execute a bundle command:

remote: Bundler::LockfileError: You must use Bundler 2 or greater with this lockfile.
remote:   /app/vendor/ruby-2.6.0/lib/ruby/2.6.0/bundler/lockfile_parser.rb:108:in `warn_for_outdated_bundler_version'
remote:   /app/vendor/ruby-2.6.0/lib/ruby/2.6.0/bundler/lockfile_parser.rb:95:in `initialize'
remote:   /app/vendor/ruby-2.6.0/lib/ruby/2.6.0/bundler/definition.rb:83:in `new'

This is due to the built-in bundler integration that ships with Ruby 2.6.0. This bug is fixed in 2.6.1. If you hit the above error message with bundler 2.0.1, then please upgrade your Ruby version to use the latest version of 2.6.x.

2) When using binstubs to run a command instead of bundle exec the wrong version of Bundler can get activated when using Ruby 2.6.x. This bug is reported to Ruby Core and will be fixed when Ruby 2.6.3 is released. Please use the latest version of 2.6.x.

In the short term, the workaround is to ensure all commands in the Procfile and app.json are prefaced with bundle exec. For example:

web: bundle exec bin/rails server -p $PORT -e $RAILS_ENV
worker: bundle exec sidekiq -C config/sidekiq.yml

Technically this bug was fixed with 2.6.2 but there are other bugs with that version so we recommend 2.6.3+. Please use the latest version of 2.6.x.

3) Ruby 2.5.x does not work with Bundler 2 unless the EXACT same version of bundler is specified in the Gemfile.lock.

This behavior is reported in Bundler check incorrectly fires while running on older versions of Ruby/Rubygems.

If you have a BUNDLED WITH that indicates a pre-release version such as 2.0.0.pre.1 then you might get an error that looks like this:

in `find_spec_for_exe': Could not find 'bundler' (2.0.0.pre.1) required by your Gemfile.lock. (Gem::GemNotFoundException) To update to the lastest version installed on your system, run `bundle update --bundler`. To install the missing version, run `gem install bundler:2.0.0.pre.1`

To fix this issue update your project to use the same version of Bundler locally, in this case, 2.0.1:

gem install bundler -v 2.0.1
bundle update --bundler

Check the resulting changes back into git and then re-deploy.

4) A Gemfile.lock that specifies bundler 2.0.2 does not work with bundler 2.0.1

If you attempt to deploy an app that uses bundler 2.0.2 onto the Heroku platform with bundler 2.0.1 you may get this error:

`find_spec_for_exe': can't find gem bundler (>= 0.a) with executable bundle (Gem::GemNotFoundException)

This is due to a bug in the Rubygems bundler version checking code. To avoid this issue, upgrade your Ruby version. It is fixed in 2.5.5+ and 2.6.3+. If you do not update, your Ruby version then every new release of Bundler 2.x will trigger this issue. Please use the latest version of 2.6.x.

Bundler 1.17.3

1) Applications using Ruby 2.6.0 and 2.6.1 will experience an error when their application attempts to boot depending on the contents of their Gemfile.lock. To fix this issue, please upgrade to Ruby 2.6.3+. Here is an example of the error:

/app/vendor/bundle/ruby/2.6.0/gems/bundler-1.17.3/lib/bundler/runtime.rb:319:in `check_for_activated_spec!': You have already activated bundler 1.17.3, but your Gemfile requires bundler 1.17.2. Prepending `bundle exec` to your command may solve this. (Gem::LoadError)

Please use the latest version of 2.6.x.

Bundler 1.15.x

1) If you are getting this output while upgrading:

remote:        Bundler Output: You are trying to install in deployment mode after changing
remote:        your Gemfile. Run `bundle install` elsewhere and add the
remote:        updated Gemfile.lock to version control.

But locally running bundle install does not change your Gemfile.lock please make sure you’re using a recent version of bundler locally. We recommend 1.13.7 or above. Once you have upgraded your local bundler version please re-run bundle install and commit the results to git before deploying again.

If running bundle install and committing the results does not resolve the issue, check to see if you have any custom gem sources that use an ENV var. For example:

source "https://#{ENV['GEMFURY_URL'}@gem.fury.io/some-value-here/"

If you are using an ENV var to specify a username or password for a source in your Gemfile, make sure you are running bundle install locally with the same ENV var. Also verify and that the full URL including any username or password is present in your Gemfile.lock after bundling.

If you do not wish for your username and password to be checked into git, consider using bundler’s built in support for configuring username and password via a special ENV var.

• Specifying BUNDLE_GEMFILE with relative path may not work https://github.com/rubygems/bundler/pull/5815.

Bundler 1.13.6

1) There is a bug where if you are using an older version of bundler locally, it will allow you to have a version of Ruby in your Gemfile.lock that is not valid according to the ruby declaration in your Gemfile. You may get an output that looks like this

Your Ruby version is 2.2.5, but your Gemfile specified 2.3.1

When you see this, upgrade to the latest bundler locally gem install bundler and then run bundle install. Make sure this updates the Ruby version in your Gemfile.lock. If it doesn’t you can run

$ bundle update --ruby

Original bug issue: Bundler allows Incompatible Ruby versions in Gemfile and Gemfile.lock.

2) If you are using Ruby 1.9.3 or Ruby 2.0.0, there is a bug where the patch version in your Gemfile.lock may not be present on Heroku.

For 1.9.3 to fix this, upgrade to 1.9.3p551 locally and run bundle update --ruby with a recent version of bundler. Check your Gemfile.lock to make sure you see the patch level p551 listed in your Ruby version.

For 2.0.0 to fix this, upgrade to 2.0.0p648 locally and run bundle update --ruby with a recent version of bundler. Check your Gemfile.lock to make sure you see the patch level p648 listed in your Ruby version.

We also recommend you upgrade from 1.9.3 and 2.0.0 as they are EOL via Ruby core. You can see currently supported ruby versions listed here.

Bundler 1.13.1

1) There was a bug fix in the way that required Ruby versions are handled. You may get an error like this:

Bundler Output: requires_greater_than_equal_ruby_two_two-0.1.0 requires ruby version >= 2.2.2, which is incompatible with the current version, ruby 2.1.7p400

If that happens, you need to upgrade your version of Ruby to be compatible with the minimum Ruby version specified in your gems.

Bundler 1.11.2

1) When upgrading from version 1.9.7 to 1.11.2 there was a change in how gemspec validations are used. Your app may be running with a gem that currently does not have a valid gemspec. If that is the case you may get an error like this in some part of your deploy output:

 The gemspec at /tmp/build_869ace36768a67943b91e3d7d7d4c576/vendor/gems/<gem-path>.gemspec is not valid. The validation error was '"FIXME" or "TODO" is not a description'
 The gemspec at /tmp/build_869ace36768a67943b91e3d7d7d4c576/vendor/engines/<path>.gemspec is not valid. The validation error was '"FIXME" or "TODO" is not a description'
 rake aborted!
 LoadError: cannot load such file -- <gem-name>

Look for lines that start "The gemspec at", identify the problem that is in the warning and fix it. The above example is of a gemspec that has `“TODO” in the description.

Another example of this class of error is:

The gemspec at /tmp/build_a965713cdcd547733e1dc9dd119dd04b/vendor/bundle/ruby/2.1.0/bundler/<gem-path>.gemspec is not valid. The validation error was 'duplicate dependency on <gem> (~> 0.4.3, development), (>= 0.4.0) use:       add_runtime_dependency '<gem>', '~> 0.4.3', '>= 0.4.0'
Could not find <gem>-1.1.0 in any of the sources

In this case, the gem that was being installed had a duplicate dependency of itself in the gemspec. This was resolved by removing the duplicate.

2) The implicit behavior of the --without flag changed between 1.9.7 and 1.11.2. For more information see Bundle without change in implicit behavior in v1.10.0.

Support

Before opening a support ticket, first determine if the problem still occurs using an older version Bundler. If you can reproduce the issue on an older version of Bundler it indicates that the problem is not related to the Bundler change. Please include build output and whether or not the build also failed using an older version of Bundler when communicating to our support staff.

Make sure you’re using the latest supported Ruby version. You can get support at https://help.heroku.com.