Gem::LoadError: ...

Gem::LoadError means RubyGems found the gem but couldn’t activate it — the required version doesn’t match what’s installed, or a dependency conflicts.

What It Means

Unlike a simple “cannot load such file” error, Gem::LoadError means the gem is physically present on disk but Ruby refuses to load it. The most common variant is Gem::LoadError: can't activate <gem> (<version requirements>), already activated <gem> (<other version>). This means two different parts of your app (or Bundler and your app) disagree on which version to use.

Why It Happens

• Multiple gem versions are installed and the wrong one is activated first.
• Bundler.setup isn’t called before requiring gems.
• The Gemfile.lock specifies a version that’s not installed.
• You switched Ruby versions but didn’t reinstall the gems.
• A gemspec in a development project specifies conflicting dependencies.
• Rails or framework boots gems before Bundler has set up the load path.

How to Fix It

Step 1: Run bundle install to sync your lock file

bundle install

This installs any missing gem versions and updates the lock file.

Step 2: Use bundle exec to run commands

Instead of running your script directly:

# This may load the wrong gem versions:
ruby app.rb

# This respects your Gemfile:
bundle exec ruby app.rb

Step 3: Check for duplicate gem version entries

Look in your Gemfile.lock for the conflicting gem:

grep -A 2 "gem-name" Gemfile.lock

If multiple versions are installed, clean up:

gem cleanup <gem-name>  # Remove all but the latest version
bundle install

Step 4: Verify Ruby version compatibility

Some gems require specific Ruby versions:

ruby --version
# Check if the gem supports your Ruby version in its docs or gemspec

Step 5: Delete and regenerate Gemfile.lock

If the lock file is corrupted:

rm Gemfile.lock
bundle install

This resolves all dependencies from scratch — but only do this if you understand the implications of changing dependency versions.

Step 6: Use Bundler.setup in non-Rails scripts

# At the top of your script, before any require:
require 'bundler/setup'
require 'sinatra'  # Now Bundler controls the load path