Bundler のバージョン

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2024年04月24日(水)

Ruby アプリケーションを Heroku にデプロイすると、いずれかのバージョンの Bundler​ がインストールされ、アプリケーションの依存関係をダウンロードするために使用されます。使用される Bundler のバージョンは設定できません。デプロイされている現在の Bundler のバージョンを確認するには、Ruby サポート​ページを参照してください。

Bundler のバージョンを設定できない理由

Bundler のバージョンによって、既知のバグは異なり、動作もわずかに異なります。Heroku での Bunder バージョンは、注意深く選定されています。新しい Bundler 機能のサポートと安定性の間でバランスをとる必要があります。Bundler のバージョンのキュレーションに Heroku が費やす労力により、最大の安定性が保証されます。また、Bundler のバージョンが変わったときや、Heroku によってバグが修正されたりセキュリティの問題にパッチが適用されたりしたときの非推奨化および通知のサイクルが回避されます。

Heroku での Ruby エクスペリエンスは Heroku Ruby Buildpack​ によって提供されます。これは、Bundler のバージョンをインストールし、アプリケーションのセットアップに必要なすべてのコマンドを実行するツールです。buildpack は、一般公開されている Bundler の内部動作に依存しています。現在指定されているバージョンの Bundler に対して機能することがテストされ、確認されています。最新の buildpack を古いバージョンの Bundler に対して使用すると、高い確率で予測不能な結果が生じます。

Bundler のバージョン変更に注意する

Bundler のバージョンが変更される場合、Heroku Changelog​ で告知され、Ruby サポート​ページが更新されます。

Bundler のバージョンは通常、入念に確認および検証され、リリースは頻繁ではありません。

現在サポートされているバージョンの Bundler をアプリで使用していない場合はどうなりますか?

アプリケーションで使用している Bundler のバージョンが Ruby サポート​の記事に掲載されているものと異なる場合、Ruby buildpack のマスターブランチをデプロイに使用するようにアプリケーションが設定されている可能性があります。

設定されている buildpack を確認するには、heroku buildpacks​ コマンドを使用します。

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

出力例は、リリースされていないバージョンの buildpack が使用されていることを示しています。サポートされているバージョンに切り替えるには、次のように buildpack を設定します。

$ 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.

次のように入力することで、新しい buildpack が設定されていることを確認できます。

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

現在サポートされている Bundler バージョンをアプリで使用していない可能性がある別の理由としては、異なる buildpack URL を使用してデプロイするようにアプリが設定されている場合が考えられます。これが起きるのは、BUILDPACK_URL​ 環境設定が設定されている場合です。

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

何らかの値が設定されている場合、カスタム buildpack を使用しています。この値が https://github.com/heroku/heroku-buildpack-multi​ などの “マルチ buildpack” に設定されている場合、デプロイで使用されている buildpack を .buildpacks​ ファイルで確認する必要があります。このデプロイ方法を使用している場合は、代わりに「アプリの複数の buildpack の使用​」の記事にあるガイダンスに従うことをお勧めします。

正式にデプロイされる Ruby buildpack はマスターよりも数日遅れる場合があります。

古いバージョンの Bundler の使用

使用する Bundler のバージョンを buildpack とは無関係に指定する方法はありません。ただし、デプロイされているバージョンの Ruby buildpack にアプリをロックすることは可能です。Ruby buildpack がデプロイされると、Ruby リリースが GitHub に作成されます​。

アプリケーションを特定のリリースにロックすることは、Bundler で発生している問題の診断中またはトラブルシューティング中の一時的な手段です。古いリリースへのロックは、バグ修正や改善が buildpack に導入されたときにその恩恵を受けられないことを意味します。

古い buildpack のバージョンにロックしている場合に最もよくある問題の 1 つは、エラーの発生によってデプロイが妨げられることです。buildpack の新しいバージョンでエラーが修正されたことがわかっていても、アップグレードするためには元の非互換性を修正する必要があります。クリティカルな時期にこのような事態に陥った場合、緊急措置の方法はありません。アプリの修正に時間を費やす必要があります。常に最新バージョンを使用し、特定のリリースバージョンにロックしないことをお勧めします。

Heroku では、古いリリースへのロックが永久に機能することを保証しません。プラットフォームの変更によって、履歴バージョンとの非互換性が導入される可能性があります。ロックされたリリースを使用してデプロイしている間に新しい問題が発生した場合、お客様が最新のリリースにアップグレードしない限り Heroku ではトラブルシューティングを実施できません。いかなる修正も古いリリースにさかのぼって移植されることはありません。以上の問題を避けるために、特定のリリースへのロックは短い期間に限定してください。

特定のリリースバージョンを使用するために、buildpack:set​ コマンドを使用し、URL 内のポンド記号 (#​) に続けてリリースを指定できます。v224​にロックするために、次のコマンドを実行できます。

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

次回のデプロイ時に Ruby buildpack のバージョン v224​ を取得することになります。Heroku Ruby Buildpack Changelog​ を使用すると、特定のバージョンの Bundler がデプロイされたタイミングを確認できます。

特定のバージョンの Bundler を使用しているときにアプリでエラーが発生する場合、そのバージョン番号を検索して、デプロイされたタイミングを確認できます。それよりも前のバージョンを使用してデプロイするようにアプリを一時的に設定できます。たとえば、バージョン 1.11.2 を使用するとアプリでエラーが発生する場合、"1.11.2" を検索し、この変更が導入される前の最後のデプロイが v144 であったことを確認し、v144​ にロックすることができます。

特定のリリースへのロックは、根本の問題を診断して修正できるまでの間の一時的な対策にすぎないということは覚えておいてください。

既知のアップグレードの問題

Bundler 2.4.22 および 2.5.6

2024 年 2 月 28 日​に Bundler のバージョン検出ロジックがアップグレードされ、BUNDLED WITH​ 2.4.x および 2.5.x のアプリケーションの場合は、それぞれ Bundler 2.4.22 および 2.5.6 を受け取ります。この変更によりアプリケーションのデプロイが失敗するようになった場合は、まず Gemfile.lock​ の BUNDLED WITH​ を次の内容に置き換えて、Bundler の最後の以前のバージョンでデプロイを試します。

BUNDLED WITH
   2.3.25

完了したら、結果を git にコミットし、再度デプロイを試みます。

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

ビルド出力の Bundler のバージョンが 2.3.25​ になっていることを確認します。失敗が解消された場合は、Bundler にバグがあることを示している可能性があります。失敗が続く場合は、問題はアプリケーション内にあり、Bundler のバージョンとは関係がないと考えられます。

Bundler 2.4.22

Bundler 2.4 より前では、Gemfile.lock​ に記録されずに Gemfile で ruby​ バージョンを指定できました。アプリケーションが予期せず Ruby のデフォルトバージョンを使用していると報告した場合は、Gemfile​ に Ruby 宣言があることを確認してください。その後、以下を実行します。

$ bundle update --ruby

Gemfile.lock​ に RUBY VERSION​ が存在することを確認してください。たとえば、Ruby 3.2.2 を使用している場合は、ファイルの下部に次の内容が表示されます。

RUBY VERSION
   ruby 3.2.2p53

Gemfile.lock​ に RUBY VERSION​ を追加したら、それを git にコミットして再度デプロイを試します。

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

Bundler 2.2.3 以降

Bundler 2.2.3 でローカルに生成されたアプリの Gemfile.lock は、Linux プラットフォームが明示的に “ロック” されていない場合、Heroku では機能しない可能性があります。

$ 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

2.0.1 の問題を参照してください。Ruby 2.6.x および 2.5.x の最新バージョンを使用​してください。

多くのユーザーで、新しい Bundler バージョンがリリースされた場合にのみトリガーされる問題 4 (後述) が発生しています。発生原因は RubyGems のバグであり、2.5.x および 2.6.x の最新バージョンにアップグレードすることによって解決できます。

Bundler 2.0.1

1) Ruby 2.6.0 を使用してデプロイしている場合は、dyno またはリリースフェーズコマンドが bundle​ コマンドを実行しようとするとエラーが発生します。

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'

これは、Ruby 2.6.0 に同梱されている組み込みの Bundler 統合が原因です。このバグは 2.6.1 で修正されています。Bundler 2.0.1 で上記のエラーメッセージが表示される場合は、2.6.x の最新バージョンを使用​するように Ruby バージョンをアップグレードしてください。

2) Ruby 2.6.x を使用しているときに、bundle exec​ の代わりに binstubs を使用してコマンドを実行すると、誤ったバージョンの Bundler がアクティブになる可能性があります。このバグは Ruby Core に報告​されており、Ruby 2.6.3 のリリース時に修正される予定です。2.6.x の最新バージョンを使用​してください。

短期的な回避策は、Procfile​ と app.json​ ですべてのコマンドの前に必ず bundle exec​ を付けることです。たとえば、次のようになります。

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

技術的にはこのバグは 2.6.2 で修正されましたが、2.6.2 には他にもバグがあるため、2.6.3 以降をお勧めします。2.6.x の最新バージョンを使用​してください。

3) 完全に同じバージョンの Bundler が Gemfile.lock​ で指定されていない限り、Ruby 2.5.x は Bundler 2 では機能しません。

この動作は、こちら​ (古いバージョンの Ruby/RubyGems で実行中に Bundler のチェックが誤って発動する) で報告されています。

2.0.0.pre.1​ などのプレリリースバージョンを示す BUNDLED WITH​ がある場合、次のようなエラーが発生する可能性があります。

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`

この問題を修正するには、同じバージョンの Bundler (この場合は 2.0.1) をローカルで使用するようにプロジェクトを更新します。

gem install bundler -v 2.0.1
bundle update --bundler

行った変更を Git に再びチェックインしてから、再デプロイします。

4) Bundler 2.0.2 を指定する Gemfile.lock は、Bundler 2.0.1 では機能しません。

Bundler 2.0.2 を使用するアプリを、Bundler 2.0.1 を使用している Heroku プラットフォームにデプロイしようとすると、次のエラーが発生する場合があります。

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

これは、Bundler のバージョンをチェックする RubyGems コードのバグが原因です。この問題を回避するには、Ruby のバージョンをアップグレードします。2.5.5 以降および 2.6.3 以降で修正されています。Ruby のバージョンを更新しない場合、Bundler 2.x の新しいリリースのたびにこの問題が発生します。2.6.x の最新バージョンを使用​してください。

Bundler 1.17.3

1) Ruby 2.6.0 および 2.6.1 を使用しているアプリケーションで、Gemfile.lock の内容に従ってアプリケーションが起動しようとすると、エラーが発生します。この問題を修正するには、Ruby 2.6.3 以降にアップグレードしてください。エラーの例を次に示します。

/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)

2.6.x の最新バージョンを使用​してください。

Bundler 1.15.x

1) アップグレード中に次の情報が出力されるとします。

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.

ただし、ローカルで bundle install​ を実行しても Gemfile.lock​ は変わりません。最新バージョンの Bundler をローカルで使用していることを確認してください。1.13.7​以上をお勧めします。ローカルの Bundler のバージョンをアップグレードしたら、bundle install​ を再実行し、結果を Git にコミットしてから、再度デプロイしてください。

bundle install​ を実行して結果をコミットしても問題が解決しない場合は、ENV 変数を使用するカスタム gem ソースがあるかどうかを確認してください。次に例を示します。

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

Gemfile​ で ENV 変数を使用してソースのユーザー名またはパスワードを指定している場合、ローカルで bundle install​ を実行するときに同じ ENV 変数を使用していることを確認してください。また、バンドル後、ユーザー名またはパスワードを含む完全な URL が Gemfile.lock​ に存在していることを確認してください。

ユーザー名とパスワードを Git にチェックインしたくない場合は、特別な ENV 変数によってユーザー名とパスワードを設定するための Bundler の組み込みサポート​の使用を検討してください。

Bundler 1.13.6

1) 古いバージョンの Bundler をローカルで使用している場合に、Gemfile での ruby​ 宣言によると有効ではないバージョンの Ruby を Gemfile.lock​ に含めることができるというというバグがあります。次のように出力される場合があります。

Your Ruby version is 2.2.5, but your Gemfile specified 2.3.1

このように表示された場合は、ローカルで最新の Bundler にアップグレード (gem install bundler​) してから bundle install​ を実行してください。これによって Gemfile.lock​ で Ruby のバージョンが更新されることを確認してください。更新されない場合は、次を実行してください。

$ bundle update --ruby

元のバグの問題: ​Bundler allows Incompatible Ruby versions in Gemfile and Gemfile.lock​ (Gemfile と Gemfile.lock で Ruby のバージョンに互換性のないことが Bundler で見落とされる)。

2) Ruby 1.9.3 または Ruby 2.0.0 を使用している場合、Gemfile.lock 内のパッチバージョンが Heroku 上に存在しない場合があるというバグがあります。

1.9.3 でこれを修正するには、ローカルで 1.9.3p551​ にアップグレードし、最新バージョンの Bundler を使用して bundle update --ruby​ を実行します。Gemfile.lock​をチェックして、Ruby のバージョンのパッチレベルが p551​ になっていることを確認します。

2.0.0 でこれを修正するには、ローカルで 2.0.0p648​ にアップグレードし、最新バージョンの Bundler を使用して bundle update --ruby​ を実行します。Gemfile.lock​をチェックして、Ruby のバージョンのパッチレベルが p648​ になっていることを確認します。

1.9.3 および 2.0.0 は Ruby Core でサポートが終了しているため、これらのバージョンからアップグレードすることもお勧めします。現在サポートされている Ruby のバージョンの一覧​を確認してください。

Bundler 1.13.1

1) 必要な Ruby バージョンの取り扱いに関してバグ修正がありました。次のようなエラーが発生する場合があります。

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

その場合は、Ruby のバージョンをアップグレードし、gem で指定されている最小 Ruby バージョンとの互換性を確保する必要があります。

Bundler 1.11.2

1) バージョン 1.9.7 から 1.11.2 へのアップグレードに際して、gemspec 検証の使用方法に変更がありました。gemspec の有効性が切れている gem を使用してアプリを実行している可能性があります。その場合、デプロイ出力の一部に次のようなエラーが記録されることがあります。

 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>

"The gemspec at"​ で始まる行を探し、警告されている問題を特定して修正してください。上記は “TODO” が説明に含まれている gemspec の例です。

このクラスのエラーには、次のような例もあります。

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

この例では、インストール中だった gem について、それ自体の重複した依存関係が gemspec に存在していました。これは、重複を削除することによって解決しました。

2) --without​ フラグの暗黙的な動作は、1.9.7 から 1.11.2 までの間に変更されています。詳細は、「Bundle without change in implicit behavior in v1.10.0​」(v1.10.0 の Bundle で暗黙的動作が変更されていない) を参照してください。

サポート

サポートチケットを開く前に、まず、古いバージョンの Bundler を使用しても同じように問題が発生するかどうかを確認してください。古いバージョンの Bundler で問題を再現できる場合、問題が Bundler の変更に関連していないことを示しています。サポートスタッフに連絡するときは、ビルドの出力を添付し、古いバージョンの Bundler を使用してもビルドが失敗したかどうかを伝えてください。

サポートされている Ruby のバージョン​のうち最新のものを使用していることを確認してください。サポートが必要な場合は、https://help.heroku.com​ にアクセスしてください。