Fix Bundler GemNotFoundException with Ruby and RVM

You will learn how RubyGems locates executable gems such as Bundler, why sudo can create conflicting installations when using RVM, and how to diagnose and repair the Ruby environment selected for a Jekyll project.

Ruby libraries are packaged as gems. RubyGems installs gems into a gem directory, often called a gem home. Bundler is itself a gem, but it also provides the bundle command.

When you type bundle, Ruby runs a small executable wrapper. That wrapper asks RubyGems to locate an installed gem named bundler. The error:

can't find gem bundler (>= 0.a)

means Ruby found a bundle wrapper, but the Ruby environment currently running it cannot find the Bundler gem that wrapper needs.

This commonly happens when multiple Ruby environments exist on one computer:

• macOS may include a system Ruby.
• RVM can install separate Ruby versions and separate gemsets.
• sudo runs commands as root, often with different paths and gem directories.
• Shell configuration can select one bundle executable while Ruby uses another environment.

With RVM, gems should normally be installed as your regular user. Running sudo bundle install may install files with root ownership or use a different Ruby/Gem directory. It does not reliably install project dependencies into your active RVM environment.

The RVM warning is separate but important: RVM is reading the project's Gemfile to decide which Ruby to use. A Gemfile entry such as ruby RUBY_VERSION is not a concrete Ruby version for RVM to interpret. Use a literal version such as ruby "2.3.5", or use a .ruby-version file.

Think of each Ruby installation or RVM gemset as a separate toolbox.

• Ruby is the workshop.
• Gems are tools stored in that workshop.
• Bundler is one specific tool.
• The bundle command is a label pointing to the tool.

If the label comes from toolbox A but your shell is currently using toolbox B, Ruby looks in toolbox B and cannot find the tool. Installing gems with sudo is like putting a tool in a locked administrator-only toolbox: your regular RVM workshop may still not be able to use it.

The fix is to select the intended Ruby workshop, install Bundler there without sudo, and then install the project's dependencies there.

First, inspect which executables and gem directories your shell is using:

which ruby
which gem
which bundle
ruby -v
gem env home
gem list bundler

When RVM is active, the paths for ruby, gem, and bundle commonly include .rvm. They should refer to the same Ruby version or gemset.

Install Bundler into the currently selected Ruby environment:

gem install bundler

Then verify it:

bundle --version
gem list bundler

Install the dependencies declared by the project:

cd /Library/WebServer/Documents/blog
bundle install
bundle exec jekyll serve

Use bundle exec for project commands. It runs Jekyll with the exact gem versions resolved in Gemfile.lock, rather than whichever Jekyll happens to be installed globally.

If the project deliberately requires an older Bundler version, install that version explicitly:

gem install bundler -v 1.17.3
bundle _1.17.3_ install

Do this only when the project's Gemfile.lock or documentation requires it. Ruby 2.3 and Jekyll 3.6 are old releases, so a modern Bundler version may not be compatible with that project.

Consider this normal command sequence:

cd ~/Sites/my-blog
bundle exec jekyll serve

Here is what happens:

1. cd changes the current directory to the Jekyll project. Bundler can now find the project's Gemfile.
2. Your shell finds the bundle executable by searching directories in PATH.
3. The executable wrapper starts Ruby and asks RubyGems to activate the bundler gem.
4. RubyGems searches the gem directories for the currently active Ruby or RVM gemset.
5. Bundler reads Gemfile and Gemfile.lock to select dependency versions.
6. bundle exec starts jekyll using those selected gems.
7. Jekyll builds the site and starts a local development server.

In the reported failure, execution stops at step 4: the wrapper was found, but the active gem directory does not contain a usable bundler gem.

A safe recovery sequence is:

# Select the Ruby that the project is intended to use.
rvm use 2.3.5

# Confirm the selected environment.
ruby -v
gem env home

# Install Bundler in this environment as the normal user.
gem install bundler

# Enter the project and install its dependencies.
cd /Library/WebServer/Documents/blog
bundle install
bundle exec jekyll serve

If rvm use 2.3.5 reports that the Ruby is not installed, install it through RVM first, then repeat the sequence:

rvm install 2.3.5
rvm use 2.3.5
gem install bundler

Bundler is used whenever a Ruby application needs repeatable dependencies.

• Jekyll sites: Ensure every contributor builds a site with the same Jekyll and plugin versions.
• Rails applications: Start servers, tests, and database tasks with gems from the application's bundle.
• CI pipelines: Run bundle install before tests so automated jobs use versions locked in Gemfile.lock.
• Deployment platforms: Recreate the application's dependency set from Gemfile and Gemfile.lock.
• Developer machines with multiple projects: Keep an older project on older gem versions without breaking a newer project.

For example, a project may require Jekyll 3 while another project requires Jekyll 4. bundle exec jekyll serve makes each command use the version belonging to its own project.

In real Ruby projects, developers usually commit these files:

• Gemfile: declares direct dependencies and optional Ruby version requirements.
• Gemfile.lock: records the exact resolved gem versions.
• .ruby-version: states the intended Ruby version for tools such as RVM, rbenv, or asdf.

A minimal Jekyll-related Gemfile can look like this:

source "https://rubygems.org"

ruby "2.3.5"

gem "jekyll", "~> 3.6"

A more reliable approach for Ruby selection is a .ruby-version file containing only the version:

2.3.5

Teams commonly use these patterns:

• Run bundle install after cloning a repository or changing the Gemfile.
• Run project tools through bundle exec, such as bundle exec rake test or bundle exec jekyll serve.
• Avoid sudo with RVM, rbenv, and other per-user Ruby managers.
• Keep the Ruby version, Bundler version, and lockfile compatible, especially in older projects.
• Check executable locations with which ruby and which bundle when an environment error occurs.

Using sudo with an RVM-managed Ruby

sudo bundle install

This can run Bundler under root's environment instead of your RVM environment. It can also leave files owned by root in the project directory.

Prefer:

bundle install

If a previous sudo command created root-owned files in the project, correct ownership carefully for that project directory:

sudo chown -R "$USER" /Library/WebServer/Documents/blog

Only run this on a directory you own and intend to repair.

Assuming jekyll serve uses the project version

jekyll serve

This may run a globally installed Jekyll, or it may fail if that global gem is missing. Prefer:

bundle exec jekyll serve

Mixing Ruby installations

A system Ruby executable and an RVM bundle executable can produce confusing errors. Check all three commands:

which ruby
which gem
which bundle

They should belong to the same environment.

Treating RUBY_VERSION as a version declaration

This is not a stable Ruby-manager declaration in a Gemfile:

ruby RUBY_VERSION

Use a literal supported version instead:

ruby "2.3.5"

Or put 2.3.5 in .ruby-version.

Deleting Gemfile.lock immediately

Removing the lockfile can force Bundler to resolve newer gems, which may no longer support an older Ruby such as 2.3. First try installing the Bundler version expected by the existing lockfile. Change the lockfile only intentionally.

# Diagnose the active environment
which ruby
which gem
which bundle
ruby -v
gem env home
gem list bundler

# Select an RVM Ruby
rvm use 2.3.5

# Install Bundler for that Ruby; do not use sudo with RVM
gem install bundler

# Install a project's dependencies
cd path/to/project
bundle install

# Run the project-specific Jekyll
bundle exec jekyll serve

Key rules:

• Install gems into the same Ruby environment that will run them.
• With RVM, use normal user commands, not sudo.
• Prefer bundle exec for commands supplied by a project.
• Keep Gemfile.lock when working with an existing project.
• Use a concrete Ruby version in .ruby-version or Gemfile; do not use an unresolved RUBY_VERSION token for RVM selection.

Why does Ruby say it cannot find Bundler when bundle -v previously worked?

Your shell environment may have changed, or the bundle wrapper may be present while the Bundler gem is absent from the currently selected Ruby or gemset. Run which bundle, ruby -v, and gem list bundler in the same terminal session.

Should I use sudo bundle install on macOS?

Not when using RVM. RVM installs Rubies and gems under your user account. Use bundle install without sudo.

What does bundle exec do?

It runs a command with the gem versions resolved for the current project. For Jekyll, use bundle exec jekyll serve to avoid accidentally using another installed Jekyll version.

How do I install Bundler for the active Ruby version?

Select the intended Ruby, then run:

rvm use 2.3.5
gem install bundler

Why does RVM complain about RUBY_VERSION in my Gemfile?

RVM expects a Ruby version it can understand. Replace an expression such as ruby RUBY_VERSION with a concrete value such as ruby "2.3.5", or create a .ruby-version file containing 2.3.5.

Do I need to reinstall every gem after changing Ruby versions?

Usually yes. Each Ruby version and RVM gemset has its own gem directory, so installing Bundler under one Ruby does not install it under another.

Is Ruby 2.3 still a good choice for a new Jekyll site?

Ruby 2.3 is end-of-life. It may be necessary for an existing older project, but a new project should generally use a currently supported Ruby and compatible Jekyll dependencies.

• RubyGems — The package manager and gem activation system that locates Bundler.
• Bundler and Gemfile — Declaring and installing a project's Ruby dependencies.
• Gemfile.lock — Locking exact dependency versions for reproducible builds.
• RVM gemsets — Isolated groups of gems for different Ruby projects.
• Ruby version managers — Tools such as RVM, rbenv, and asdf that select Ruby installations.
• PATH environment variable — Determines which ruby, gem, and bundle executable your shell runs.
• File ownership and sudo — Explains why administrator commands can cause permission and environment conflicts.
• Jekyll development server — Serving and rebuilding a static site locally.