Last updated June 30, 2021
Table of Contents
When deploying a Ruby application to Heroku, a version of Bundler will be installed and used to pull down the dependencies of your application. The Bundler version that is used is not configurable. To see the current Bundler version deployed, see the Ruby Support page.
Why can’t the Bundler version 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
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 application than is listed in the Ruby Support article, your application might be configured to use the master 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
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.
Locking your application to a release should be a temporary measure while you diagnose or troubleshoot the problem you are having with Bundler. Locking to an older release means that when bug fixes and improvements are introduced to the buildpack you will not get them.
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
Remember that locking to a release should only be a temporary fix until you can diagnose and fix the root problem.
Known upgrade issues
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"
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.
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
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
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
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.
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.
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.
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:
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.
BUNDLE_GEMFILEwith relative path may not work https://github.com/bundler/bundler/pull/5815.
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.
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.
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.
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.