quarkusio/quarkus · error · java.lang.IllegalStateException

Matching scheduler implementation not found:

Error message

Matching scheduler implementation not found: 

What it means

When scheduling a job with an explicit executeWith implementation, CompositeScheduler looks up the matching backing Scheduler. This is a safety net: if no backing scheduler matches the implementation string at schedule time, scheduling fails with this IllegalStateException (the name was accepted earlier but no backend provides it).

Source

Thrown at extensions/scheduler/runtime/src/main/java/io/quarkus/scheduler/runtime/CompositeScheduler.java:164

                if (schedulers.stream().map(Scheduler::implementation).noneMatch(implementation::equals)) {
                    throw new IllegalArgumentException("Scheduler implementation not available: " + implementation);
                }
            }
            return super.setExecuteWith(implementation);
        }

        @Override
        public Trigger schedule() {
            String impl = implementation;
            if (Scheduled.AUTO.equals(impl)) {
                impl = schedulerContext.autoImplementation();
            }
            for (Scheduler scheduler : schedulers) {
                if (scheduler.implementation().equals(impl)) {
                    return copy(scheduler.newJob(identity)).schedule();
                }
            }
            throw new IllegalStateException("Matching scheduler implementation not found: " + implementation);
        }

        private JobDefinition<?> copy(JobDefinition<?> to) {
            to.setCron(cron);
            to.setInterval(every);
            to.setDelayed(delayed);
            to.setOverdueGracePeriod(overdueGracePeriod);
            to.setConcurrentExecution(concurrentExecution);
            to.setTimeZone(timeZone);
            to.setExecutionMaxDelay(executionMaxDelay);
            to.setDescription(description);
            to.setExecuteWith(implementation);
            if (skipPredicateClass != null) {
                to.setSkipPredicate(skipPredicateClass);
            } else if (skipPredicate != null) {
                to.setSkipPredicate(skipPredicate);
            }
            if (taskClass != null) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the scheduler extension providing the implementation is included and initialized
2. Use Scheduled.AUTO instead of pinning a specific implementation
3. Verify the composite's schedulers list contains the implementation at runtime (log scheduler.implementation() values)
4. Rebuild the application after adding/removing scheduler extensions so metadata matches

Example fix

// before
scheduler.newJob("id").setExecuteWith("custom").schedule(); // "custom" not registered
// after
scheduler.newJob("id").setExecuteWith(Scheduled.AUTO).schedule();
// or add the extension registering the "custom" scheduler

boolean registered = schedulers.stream()
    .anyMatch(s -> s.implementation().equals(impl));
if (!registered) throw new IllegalStateException("Backend not registered: " + impl);

try { scheduler.newJob(id).setExecuteWith(impl).schedule(); }
catch (IllegalStateException e) { scheduler.newJob(id).setExecuteWith(Scheduled.AUTO).schedule(); }

When it happens

Trigger: JobDefinition.setExecuteWith("impl") where "impl" equals the job definition's implementation field but no Scheduler in the composite reports that implementation().

Common situations: Composite scheduler assembled without the backend that was referenced; race/registration mismatch between build-time metadata and runtime schedulers; custom scheduler not actually registered at runtime.

Related errors

• No datasource named '<dataSourceName>' exists
• Not implemented yet
• Proxy configuration with name ${key} was requested but quark
• Quartz scheduler is either explicitly disabled through quark
• Cannot cache `null` value

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d54b679996e29446. Report an issue: GitHub.