Ruby "LoadError: cannot load such file" for Your Own File in CI

Ruby could not find a file you asked it to require. Unlike a missing gem, this is one of your own files - the require path or the load path ($LOAD_PATH) does not resolve to it from where the code runs in CI.

What this error means

A require or require_relative raises "LoadError: cannot load such file -- <path>" for a file that clearly exists in the repo. It usually means the working directory or load path on the runner differs from local.

Ruby traceback

<internal:.../kernel_require.rb>:in `require': cannot load such file --
./lib/parser (LoadError)
	from script.rb:3:in `<main>'

Common causes

require uses a path relative to the wrong directory

require "./lib/parser" resolves relative to the process working directory, not the script. If CI runs the script from a different directory, the relative path misses.

The directory is not on $LOAD_PATH

require "parser" only works if its directory is on the load path. Without adding lib to $LOAD_PATH (or using require_relative), the file is not found.

How to fix it

Use require_relative or add to the load path

require_relative resolves relative to the current file, independent of the working directory.

Ruby

# instead of: require './lib/parser'
require_relative 'lib/parser'
# or add the dir to the load path
$LOAD_PATH.unshift File.expand_path('lib', __dir__)
require 'parser'

Run from a consistent working directory

Set working-directory for the step so relative requires resolve.
Prefer ruby -Ilib to put lib on the load path for the run.
For tests, configure the load path in the test helper rather than per-file.

How to prevent it

Prefer require_relative over working-directory-relative require.
Set the load path in one place (test helper, -Ilib) rather than ad hoc.
Run scripts from a defined working-directory in CI.