sidekiq-requeue_missing_class helps you survive rolling deploys that introduce a new Sidekiq/ActiveJob class: instead of erroring, jobs whose class is not loadable yet are pushed back with a short delay until an updated worker picks them up.

Need help with your Sidekiq setup, background jobs architecture, or Rails performance? I'm available for consulting — get in touch.

You add a new job and deploy. Mid-rollout, a freshly started pod (or your scheduler) enqueues SendShinyNewThingJob — but the old workers are still running and don't have that class yet. An old worker pops the job and blows up:

ActiveJob::UnknownJobClassError (Not::Loaded::Yet)
# or, for a native worker:
NameError: uninitialized constant SendShinyNewThingJob

"Just deploy code before you enqueue it" is the textbook answer, and you should do that where you can. But with rolling deploys, autoscaling and schedulers, the race window is real and annoying to close by discipline alone.

The gem adds a tiny Sidekiq server middleware that, before running a job, checks whether the class meant to run it is actually loadable in this process. If it isn't, the job is pushed back with a short delay (instead of erroring), so an updated worker picks it up once the rollout finishes. After a configurable number of attempts it gives up and lets the job run — so a genuinely-missing class still surfaces the usual error instead of looping forever.

Works for both ActiveJob-over-Sidekiq and native Sidekiq jobs:

• ActiveJob jobs are wrapped, so the middleware looks at the wrapped job_class.
• Native Sidekiq jobs are checked by their worker class directly.
• "Loadable" means Object.const_get(name) succeeds (same autoloading path Sidekiq/Zeitwerk take), so classes that just need autoloading are not treated as missing.

Add the gem to your Gemfile:

gem "sidekiq-requeue_missing_class"

and require it:

require "sidekiq/requeue_missing_class"

That's it — the middleware registers itself on the server side. The check is a single constant lookup for jobs whose class is present, so the overhead for the happy path is negligible.

Sidekiq::RequeueMissingClass.configure do |c|
  c.delay = 30               # seconds before a re-queued job runs again (default: 30)
  c.max_requeues = 10        # attempts before giving up (default: 10)
  c.logger = Sidekiq.logger  # or nil to stay quiet
end

Pick delay × max_requeues to comfortably outlast your slowest rollout.

• If your deploy strategy already guarantees code-before-enqueue ordering, you may not need this.
• It only helps with the missing-class race, not with incompatible argument changes — version your job arguments separately.

The gem is available as open source under the terms of the MIT License.