Last updated January 09, 2026
When deploying a Ruby application to Heroku, a version of Bundler will be installed and used to pull down the dependencies of your application.
Version Configuration
The same bundler version found in your Gemfile.lock under the BUNDLED WITH key will be installed and used. For example, deploying an application with this Gemfile.lock contents:
BUNDLED WITH
2.6.2
Would install Bundler 2.6.2.
Known upgrade issues
Exact bundler version
As of January 9th, 2026, Heroku now uses the exact version of bundler in the Gemfile.lock, previously it converted major/minor to a “known good version.” For example, it would have converted Bundler 2.3.7 to 2.3.x, which used the latest in that series, 2.3.25.
If your application starts failing after this change, you can see the last version of bundler used in the output:
###### WARNING:
Your app was upgraded to bundler 2.3.7.
Previously you had a successful deploy with bundler 2.3.25.
If you see problems related to the bundler version please refer to:
https://devcenter.heroku.com/articles/bundler-version#known-upgrade-issues
...
-----> Installing dependencies using bundler 2.3.7
Running: BUNDLE_WITHOUT='development:test' BUNDLE_PATH=vendor/bundle BUNDLE_BIN=vendor/bundle/bin BUNDLE_DEPLOYMENT=1 bundle install -j4
[1117, #<Thread:0x00007f0d5fbafc70 run>, #<NameError: uninitialized constant Gem::Source
(defined?(@source) && @source) || Gem::Source::Installed.new
^^^^^^^^
Did you mean? Gem::SourceList>,
The error above could be fixed by installing bundler 2.3.25 locally and ensuring that version is in the Gemfile.lock. For example:
$ gem install bundler -v 2.3.25
$ bundle _2.3.25_ update --bundler
$ git add Gemfile.lock
$ git commit -m "Update Gemfile.lock"
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_GEMFILEwith 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 in the warning, and fix it. The above example is a gemspec with’ 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 being installed had a duplicate dependency in the gemspec. Removing the duplicate resolved the issue.
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.
Windows Support with Bundler 2.2 and Later
Heroku supports deploying applications developed on Windows, but production dynos will run on a different operating system). To ensure that your Heroku production application installs the same versions of gems you’re using locally for development on your Windows machine, we recommend updating your application to Bundler 2.2 or later. You can upgrade your bundler version by running the commands:
> gem install bundler
> bundle update --bundler
> bundle lock --add-platform ruby
> bundle lock --add-platform x86_64-linux
> bundle install
> git add Gemfile.lock
> git commit -m "Upgrade bundler"
After running these commands, Windows applications using bundler 2.2+ will rely on bundler’s support for multiple platforms to find and install an appropriate version.
Windows Support with Bundler Before 2.2
If your application can’t upgrade to bundler 2.2 or later, then when you deploy, the Gemfile.lock file will be deleted and regenerated. You can find more information about this behavior on the Ruby buildpack’s GitHub repository.
Support
Before opening a support ticket, first determine if the problem still occurs using an older version of 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 the build output and whether or not the build also failed using an older version of Bundler when communicating with our support staff.
Make sure you’re using the latest supported Ruby version.