Zeitwerk::NameError on autoload in CI

Zeitwerk maps file paths to constant names by convention. When a file does not define the constant Zeitwerk expects from its path, eager loading (which CI does) raises Zeitwerk::NameError.

What this error means

CI fails during boot or eager load with a Zeitwerk::NameError naming the file and the constant it expected. Development may have worked because the offending file was never loaded.

Zeitwerk::NameError: expected file
app/services/html_parser.rb to define constant HtmlParser, but didn't
(Loader#expected_constant_for)

Common causes

Filename/constant mismatch

app/services/html_parser.rb is expected to define HtmlParser, but the file defines HTMLParser (or something else). Zeitwerk does not guess acronym casing unless told.

Acronym inflection not registered

A constant like HTMLParser needs an inflection rule so Zeitwerk maps html_parser.rb to HTMLParser.

Misplaced file

A file sits in an autoload path but defines a constant whose name does not correspond to its location.

How to fix it

Align name, file, and inflections

1. Rename either the file or the constant so they correspond by Zeitwerk convention.
2. For acronyms, register an inflection: Rails.autoloaders.main.inflector.inflect("html_parser" => "HTMLParser").
3. Move the file to the directory matching its namespace.

Validate the whole tree

Run the check that CI effectively runs so the failure reproduces locally.

bin/rails zeitwerk:check

How to prevent it

• Run zeitwerk:check in CI before tests.
• Register inflections for any acronym constants.
• Keep file paths in lockstep with constant names.

Related guides