NameError: uninitialized constant in CI

Ruby tried to resolve a constant (a class or module name) and found nothing bound to it. In CI this usually means a file was not required, a name is misspelled, or the autoloader could not map the constant to a file.

What this error means

A test or boot step dies with NameError naming the constant it could not find, often with a "Did you mean?" suggestion. It frequently passes locally where files were already loaded in an interactive session.

ruby

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

Common causes

File never required

In a plain Ruby project the defining file was not required before the reference, so the constant does not exist yet at the point of use.

Name or nesting mismatch

The constant is spelled differently from its definition, or referenced outside the module nesting where it is defined, so Ruby looks in the wrong scope.

Autoload path not eager-loaded in CI

Rails eager-loads in CI (RAILS_ENV=test with eager_load on). A file in a non-standard directory or with a name that does not match its constant is invisible to Zeitwerk.

How to fix it

Require or correct the reference

Confirm the exact constant name against its definition, including module nesting.
In a plain Ruby project, add require_relative for the defining file.
In Rails, ensure the file path matches the constant (app/services/payment_processor.rb defines PaymentProcessor).

Reproduce the CI load order locally

Eager-load like CI does so the missing constant surfaces on your machine, not only on the runner.

Terminal

RAILS_ENV=test bundle exec rails zeitwerk:check
RAILS_ENV=test bundle exec rails runner 'Rails.application.eager_load!'

How to prevent it

Run rails zeitwerk:check in CI to catch name/path mismatches early.
Keep filenames in lockstep with the constants they define.
Avoid relying on lazy load order that only happens to work locally.