Last updated December 02, 2024

A “shebang” line looks like this:

#!/usr/bin/env ruby

A binstub with a bad shebang can cause your application to function improperly. Here are a few examples of errors you might get if your application has a bad Ruby shebang line:

"Your Ruby version is 2.5.1, but your Gemfile specified 2.6.6"

"Activating bundler (>= 0.a) failed ... Could not find 'bundler' (>= 0.a)"

You have already activated bundler 1.17.2, but your Gemfile requires bundler 1.17.3

This article explains binstubs, shebang lines, and the common errors that come from improperly generated binstubs.

What is a Binstub?

A “binstub” is short for “binary stub”. It is a small script found in apps that is commonly generated by bundler or a web framework. The common convention in Ruby is to put any “binstubs” in the bin/ directory of your application. Here is an example binstub from a Rails 6 project:

$ cat bin/rails
#!/usr/bin/env ruby
APP_PATH = File.expand_path('../config/application', __dir__)
require_relative '../config/boot'
require 'rails/commands'

The first line of the above binstub is:

#!/usr/bin/env ruby

This is known as a shebang line. It is a magic comment that tells unix-based operating systems how to execute your file. The preliminary #! denotes that what follows is executable. Next, /usr/bin/env provides an absolute path to the env program of the unix operating system. Finally, ruby is the name of the program that the script wants to use to execute. The combination of /usr/bin/env ruby is essentially telling the operating system to use the ruby executable that is first on the PATH.

Here’s several examples of Ruby shebang lines:

#!/usr/bin/env ruby

#!/usr/bin/env ruby2.5

#!/usr/bin/env ruby2.4

If the “shebang” line is malformed, references a non-existent binary, or a binary that is different than what you expect then your program will crash or behave in strange ways. This is an example of a common bad binstub:

#!/usr/bin/env ruby2.5

This is a “bad” binstub because when you deploy an application to Heroku we install the Ruby binary on the PATH as ruby and not as ruby2.5. To make things more confusing, the Ubuntu operating system that Heroku uses (known as the “stack”) may have this executable on the path. For example on the Heroku-18 stack:

$ heroku run bash
$ which ruby2.5
/usr/bin/ruby2.5

In this scenario, your application might be specifying you want to use Ruby 2.7.1 via the Gemfile, but if your shebang line is using ruby2.5 then it will be forced to use the wrong Ruby version. Usually, this bug causes a crash and a difficult to understand bundler error.

Correcting a bad shebang line

You can manually edit any incorrect “shebang” lines to read:

#!/usr/bin/env ruby

Once you’ve done this make sure to commit the results back to git:

$ git add .
$ git commit -m "fixing shebang lines"
$ git push heroku master

Why do binstubs exist in the Ruby ecosystem?

Files such as bin/rails were introduced to the Ruby ecosystem to alleviate the verbose call of having to write out the full command bundle exec rails. Instead, the script manually loads bundler and calls bundler setup before attempting to load a version of Rails. While that was the original intent of the files, they’re not limited to that functionality. For example prior versions also loaded up and configured the spring gem which has historically caused problems, especially when related to a version of binstubs that contained a bug.

In addition to having a bad shebang line, your binstubs might contain bugs. Over time these files may change but since they’re generated by your initial rails new <app-name> command they may be out of date. If you would like to update the binstubs on your rails project the command to do so is:

$ bin/rake app:update:bin
       exist  bin
   identical  bin/rails
   identical  bin/rake
    conflict  bin/setup
Overwrite /app/bin/setup? (enter "h" for help) [Ynaqdhm] n
        skip  bin/setup
   identical  bin/yarn

Force bundler binstub generation

To prevent this issue from happening on your next docker based project generation you can set this in your Dockerfile before generating files:

ENV BUNDLE_SHEBANG=ruby

The shebang line likely came from either Rails or bundler. Here’s a specific commit reference to a bundler template file:

#!/usr/bin/env <%= Bundler.settings[:shebang] || RbConfig::CONFIG["ruby_install_name"] %>

From this template bundler will try to find a customized “shebang” config, otherwise, it will execute the code RbConfig::CONFIG["ruby_install_name"]. If you generated your project on a docker image or if your ruby installation was “named”. Then this might have been set for you:

$ docker run -it --rm heroku/heroku:18-build  bash
root@58980a533208:/# ruby -e 'puts RbConfig::CONFIG["ruby_install_name"]'
ruby2.5