NameError: uninitialized constant when using namespaced job classes

[raihanM99]

I'm encountering an intermittent NameError: uninitialized constant when using namespaced Sidekiq job classes (e.g. DocumentAI::ProcessFileJob) with sidekiq-throttled. This happens even though the job classes are correctly defined, autoloaded by Zeitwerk, and run fine under normal conditions.

My job class is:

class DocumentAI::ProcessFileJob
  include Sidekiq::Job
  include Sidekiq::Throttled::Job

  sidekiq_throttle(
    concurrency: {
      limit: 2,
      key_suffix: ->(token, *rest) { token }
    }
  )
end

Error in my Rails log:

INFO  2025-06-13T06:24:37.788Z pid=9 tid=ktf9: /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled.rb:102:in `const_get': uninitialized constant DocumentAI (NameError)
be-1       | 
be-1       |         job_class = Object.const_get(message.fetch("wrapped") { message.fetch("class") { return false } })

This happens sporadically, especially after the worker boots, but not always reproducible — sometimes jobs run fine, sometimes this error pops up.

[raihanM99]

I simplified the structure by moving the implementation into a single top-level class (without a namespace), but the error persists.

web-1      | 172.22.21.1 - - [14/Jun/2025:06:16:01 +0000] "POST /api/v1/uploads HTTP/1.1" 200 47 "-" "PostmanRuntime/7.44.0"
be-1       | INFO  2025-06-14T06:16:01.517Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob: start
be-1       | INFO  2025-06-14T06:16:01.998Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob:   Disk Storage (4.6ms) Uploaded file to key: i6akjd56w36a9xd5qiq2gbz4np5w (checksum: 8P+dbAmgJKgZYHCniMWIGQ==)
be-1       | INFO  2025-06-14T06:16:02.044Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob: [ProcessUploadedFileJob] INITIALIZED | {"token":"1f2070a01667_1749881761","file_id":"5002dd0bfc"}
be-1       | INFO  2025-06-14T06:16:02.085Z pid=9 tid=dcx jid=5880bea6e8390e10083522a2 class=ProcessFileJob: start
be-1       | INFO  2025-06-14T06:16:02.155Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob:   Disk Storage (11.3ms) Uploaded file to key: 2mw4u2yectjbhrr3v56msdop66eg (checksum: bd9vE+7nHENiat35bmIL9Q==)
be-1       | INFO  2025-06-14T06:16:02.200Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob: [ProcessUploadedFileJob] INITIALIZED | {"token":"1f2070a01667_1749881761","file_id":"e97dc31b9d"}
be-1       | INFO  2025-06-14T06:16:02.205Z pid=9 tid=dh9 jid=a097246b128e26e652663204 class=ProcessFileJob: start
be-1       | INFO  2025-06-14T06:16:02.273Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob:   Disk Storage (9.5ms) Uploaded file to key: 3gphb13c2hudctmigzdjnlppor6n (checksum: bd9vE+7nHENiat35bmIL9Q==)
be-1       | INFO  2025-06-14T06:16:02.304Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob: [ProcessUploadedFileJob] INITIALIZED | {"token":"1f2070a01667_1749881761","file_id":"d3d1b3db66"}
be-1       | INFO  2025-06-14T06:16:02.307Z pid=9 tid=cql jid=8c98f2845726eeb811a277c4 class=ProcessUploadedFileJob elapsed=0.79: done
be-1       | INFO  2025-06-14T06:16:02.331Z pid=9 tid=dl5: /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled.rb:102:in `const_get': uninitialized constant ProcessFileJob (NameError)
be-1       | 
be-1       |         job_class = Object.const_get(message.fetch("wrapped") { message.fetch("class") { return false } })
be-1       |                           ^^^^^^^^^^
be-1       | Did you mean?  ProcessUploadedFileJob
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled.rb:102:in `requeue_throttled'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled/patches/throttled_retriever.rb:15:in `retrieve_work'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/processor.rb:92:in `get_one'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/processor.rb:104:in `fetch'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/processor.rb:86:in `process_one'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/processor.rb:77:in `run'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/component.rb:37:in `watchdog'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-8.0.4/lib/sidekiq/component.rb:46:in `block in safe_thread'
be-1       | 
be-1       | INFO  2025-06-14T06:16:02.359Z pid=9 tid=dcx jid=5880bea6e8390e10083522a2 class=ProcessFileJob: [ProcessFileJob] STARTED | {"token":"1f2070a01667_1749881761","file_id":"5002dd0bfc","jid":"5880bea6e8390e10083522a2","thread":17320}
be-1       | INFO  2025-06-14T06:16:02.377Z pid=9 tid=dlp: [ProcessFileJob] Processing batch | {"token":"1f2070a01667_1749881761","file_id":"5002dd0bfc","batch":"1_4","thread":17620}

[ixti]

Thank you for the report. Will try to come with fix asap

[ixti]

Can you tell me if you're using Rails, and if so is it using eager-load in that environment you see the error?

[raihanM99]

Can you tell me if you're using Rails, and if so is it using eager-load in that environment you see the error?

Yes, I am using Rails (but API only)

Rails version     8.0.1
Ruby version      ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux]

# I recently integrated sidekiq-throttled for the first time with these gem versions:
sidekiq (8.0.4)
  connection_pool (>= 2.5.0)
  json (>= 2.9.0)
  logger (>= 1.6.2)
  rack (>= 3.1.0)
  redis-client (>= 0.23.2)
sidekiq-throttled (2.0.0)
  concurrent-ruby (>= 1.2.0)
  redis-prescription (~> 2.2)
  sidekiq (>= 8.0)

And here is my application.rb

module App
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 8.0

    # Please, add to the `ignore` list any other `lib` subdirectories that do
    # not contain `.rb` files, or that should not be reloaded or eager loaded.
    # Common ones are `templates`, `generators`, or `middleware`, for example.
    config.autoload_lib(ignore: %w[assets tasks])

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")
    config.eager_load_paths << Rails.root.join("app/sidekiq")

    # Only loads a smaller set of middleware suitable for API only apps.
    # Middleware like session, flash, cookies can be added back manually.
    # Skip views, helpers and assets when generating a new resource.
    config.api_only = true

    config.active_job.queue_adapter = :sidekiq
    config.sidekiq_options = { config_file: "config/sidekiq.yml" }
  end
end

I initially encountered the issue before adding the app/sidekiq eager load path, and added this line as a fix:

config.eager_load_paths << Rails.root.join("app/sidekiq")

However, the problem still persists (It doesn't happen consistently) even after including that path in eager_load_paths.

[ixti]

One last bit, can you check that Zeitwerk can load your files correctly, by running:

bin/rails zeitwerk:check

Want to eliminate as many gotchas as possible before trying to propose anything :D

[raihanM99]

Sorry for the late reply — I was trying to reproduce the issue before responding.

First, regarding Zeitwerk: eager loading appears to be set up correctly. Here's the output of the zeitwerk:check task:

app % bin/rails zeitwerk:check
Hold on, I am eager loading the application.
All is good!

Now onto the actual issue. I was finally able to reproduce the error. Interestingly, it occurred while running zeitwerk:check (All is good!), after the following error appeared in the Rails logs:

be-1       | INFO  2025-06-16T06:27:00.016Z pid=9 tid=1po95: /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled.rb:102:in `const_get': uninitialized constant DocumentAI (NameError)
be-1       | 
be-1       |         job_class = Object.const_get(message.fetch("wrapped") { message.fetch("class") { return false } })
be-1       |                           ^^^^^^^^^^
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled.rb:102:in `requeue_throttled'
be-1       | 	from /gems/ruby/3.2.0/gems/sidekiq-throttled-2.0.0/lib/sidekiq/throttled/patches/throttled_retriever.rb:15:in `retrieve_work'

In my app, I have a plain Ruby class DocumentAI under app/services/ that only contains some constants:

class DocumentAI
  PROJECT_ID = 'goole_project_id'.freeze
  PROCESSOR_ID = 'google_processor_id'.freeze
  LOCATION_ID= 'us'.freeze
end

I reference these constants from a job defined at app/sidekiq/document_a_i/process_file_job.rb, which uses sidekiq_throttle:

class DocumentAI::ProcessFileJob
  sidekiq_throttle(
    concurrency: {
      limit: 1,
      key_suffix: ->(token, *rest) { token }
    }
  )

  def perform
    document_ai_client = Google::Cloud::DocumentAI.document_processor_service
    document_ai_processor_path = document_ai_client.processor_path(
      project: DocumentAI::PROJECT_ID,
      location: DocumentAI::LOCATION_ID,
      processor: DocumentAI::PROCESSOR_ID
    )
  end
end

The error uninitialized constant DocumentAI only occurs in this setup. Interestingly, once I inlined the constants directly into the job class, the issue disappeared and hasn’t reappeared since (which almost made me conclude that it wasn’t a real issue)

[ixti]

Sorry for the late reply — I was trying to reproduce the issue before responding.

I feel incredibly embarrassed. Sorry for actual late reply.

It might be related to using Foo::Bar declaration style. Can you try (if you still need this):

# file: app/services/document_a_i.rb
class DocumentAI
  PROJECT_ID = 'goole_project_id'.freeze
  PROCESSOR_ID = 'google_processor_id'.freeze
  LOCATION_ID= 'us'.freeze
end

and

# file: app/jobs/document_a_i/process_file_job.rb
class DocumentAI
  class ProcessFileJob
    include Sidekiq::Job

    # ...
  end
end

It should work.