require': cannot load such file -- ...

Ruby’s require: cannot load such file means your require or require_relative points to a file Ruby can’t find in its load path or at the relative location.

What It Means

Ruby’s require method searches for files in the directories listed in $LOAD_PATH (also known as $:). If the file you’re trying to load isn’t installed as a gem, isn’t in the project directory, or doesn’t exist at the given path, Ruby raises this LoadError. This is one of the most common errors when starting a new Ruby project or switching branches.

Why It Happens

• A required gem isn’t installed — run bundle install.
• The gem isn’t listed in your Gemfile but your app tries to load it.
• You used require instead of require_relative for a local file.
• The file path has a typo or uses the wrong case (Linux paths are case-sensitive).
• Ruby’s $LOAD_PATH doesn’t include the directory where your file lives.
• You’re running the script from the wrong directory, so relative paths don’t resolve.

How to Fix It

Step 1: Install missing gems

If the error mentions a gem name, install it:

bundle install

If there’s no Gemfile, install the gem directly:

gem install <gem-name>

Step 2: Check if the gem is in your Gemfile

Open your Gemfile and verify the gem is listed:

# Add this line if it's missing
gem 'some-gem-name'

Then run bundle install again.

Step 3: Use the correct require for local files

If the file is local (not a gem), use require_relative:

# Instead of this:
require 'helpers/parser'

# Use this:
require_relative 'helpers/parser'

Or add the directory to the load path:

$LOAD_PATH.unshift(File.dirname(__FILE__))
require 'helpers/parser'

Step 4: Verify the file path and spelling

Check that the file exists at the expected location:

ls -la lib/helpers/parser.rb

Linux paths are case-sensitive: require 'helpers/Parser' won’t find helpers/parser.rb.

Step 5: Inspect the load path

Debug where Ruby is looking:

puts $LOAD_PATH
# Run your script and check if your project directory appears

Step 6: Use Bundler.setup in standalone scripts

For scripts outside Rails:

require 'bundler/setup'
require 'some-gem'