Ruby LoadError cannot load such file — Bundler and Gems Explained

Diagnose Ruby LoadError by running through bundle exec, checking bundle check and the load path, then fixing missing gems, platform locks, and native extensions.

beginnerdebuggingrubybundler

Symptoms

LoadError: cannot load such file -- nokogiri
Bundler::GemNotFound: Could not find gem 'rails' in locally installed gems
The app runs with ruby app.rb but fails under bundle exec
Deployment fails only on a different CPU architecture or Ruby version

Possible causes

bundle install was never run in this environment or for this Ruby version
The process is not using bundle exec, so the Gemfile is ignored
The gem is in a group excluded by bundle config without the matching environment
Gemfile.lock lacks the platform used by the server, or a native extension failed to build

Diagnosis steps

Check bundle satisfaction

bundle check

Interpretation

The output lists missing gems. A satisfied bundle means the problem is the load path or the wrong executable, not missing installation.

Run the entry point through Bundler

bundle exec ruby app.rb

Interpretation

bundle exec restricts the load path to Gemfile gems. If this succeeds while plain ruby fails, the app was relying on globally installed gems.

Inspect the load path and gem environment

bundle exec ruby -e 'puts $LOAD_PATH' | head -20 && gem env home

Interpretation

The Gemfile gems should appear in the load path. gem env shows which Ruby installation is active, which often reveals an rbenv or rvm mismatch.

Check platforms and native build logs

bundle platform && bundle config list

Interpretation

A lockfile missing the server platform causes a re-resolve or install failure. Build errors for native gems point to missing compiler or library headers.

Root cause

Ruby resolves require through $LOAD_PATH. Bundler rewrites that path to the exact gem versions in Gemfile.lock, and bundle exec is what activates it. Without Bundler, or with a lockfile that does not cover the current platform, the gem is absent from the path and require raises LoadError, even if a different Ruby installation has it installed.

Fix

Run bundle install with the deployment Ruby, always start the app with bundle exec or a binstub, and add missing gems to the Gemfile rather than installing them globally. For platform errors, run bundle lock --add-platform for the server platform and install build dependencies for native extensions. Keep the Ruby version pinned in .ruby-version and the Gemfile.

Risk note

Installing a gem with sudo gem install can make tests pass locally while production still fails. Removing Gemfile.lock to fix platform issues loses pinned versions. Native extension builds need compiler packages that should not remain in the runtime image.

Verify the fix

Run bundle check and bundle exec ruby -e "require 'nokogiri'; puts Nokogiri::VERSION" to confirm the gem loads under the bundle. Start the application through bundle exec, run the test suite, and repeat in the deployment image with the same Ruby version and platform.

require follows the load path

LoadError: cannot load such file -- nokogiri

Ruby searched every directory in $LOAD_PATH and found nothing named nokogiri. Under Bundler, that path contains exactly the gems in Gemfile.lock.

Separate missing install from wrong invocation

bundle check
bundle exec ruby app.rb
bundle exec ruby -e "require 'nokogiri'; puts Nokogiri::VERSION"
bundle platform

If bundle check reports missing gems, install them. If it passes but plain ruby app.rb fails, the app was never running under the bundle. If bundle exec also fails, the gem may be in an excluded group or the lockfile may not cover this platform.

Fix the bundle

bundle config set --local path vendor/bundle
bundle install
bundle lock --add-platform x86_64-linux
bundle exec ruby app.rb

Add the gem to the Gemfile instead of gem install globally. For native extensions, install the compiler and headers (build-essential, libxml2-dev for Nokogiri on some platforms) in the build stage, not the runtime image. Pin Ruby with .ruby-version so the deployment uses the same ABI.

Verify

bundle check should be satisfied, and requiring the gem under bundle exec should print its version. Start the app through bundle exec or a binstub, run the tests, and repeat inside the deployment image. If it still fails there, compare ruby -v and bundle platform between local and server before changing the Gemfile again.