Ruby "NameError: uninitialized constant" in CI

Ruby referenced a constant - a class or module - that has not been defined or loaded yet. The defining file was never required, or an autoloader could not map the constant to its file, often because the name and path disagree.

What this error means

Code aborts with "NameError: uninitialized constant Foo" (sometimes "uninitialized constant Foo::Bar"). The constant exists in the repo but is not loaded where it is used on the runner.

Ruby traceback

NameError: uninitialized constant PaymentProcessor
	from app/services/checkout.rb:8:in `process'
Did you mean?  PaymentProcessors

Common causes

The defining file was never required

Without an autoloader, the file defining the constant must be required before use. If it is not, the constant is undefined at reference time.

Autoload/Zeitwerk name-to-path mismatch

Under Zeitwerk (Rails) the constant name must match the file path (PaymentProcessor → payment_processor.rb). A mismatched filename, wrong directory, or wrong acronym casing breaks autoloading, so the constant never resolves.

How to fix it

Require the file or fix the autoload mapping

Without an autoloader, add require/require_relative for the file that defines the constant.
Under Zeitwerk, ensure the filename matches the constant (snake_case of the name) and lives in an eager-loaded path.
For acronyms, configure inflections so HTTPClient maps to http_client.rb.

Eager-load in CI to surface the real mismatch

Eager loading turns a lazy autoload miss into an explicit, early failure naming the offending file.

Terminal

# Rails
bin/rails zeitwerk:check
RAILS_ENV=test bin/rails runner 'Rails.application.eager_load!'

How to prevent it

Match filenames to constant names under Zeitwerk.
Run zeitwerk:check (or eager load) in CI to catch mapping errors early.
Without an autoloader, require defining files explicitly.