quarkusio/quarkus · critical · IllegalStateException

Unable to start Scheduler

Error message

Unable to start Scheduler

What it means

Quarkus throws this IllegalStateException when the Quartz scheduler fails to start on application startup. The start(@Observes StartupEvent) observer calls scheduler.start(); any SchedulerException raised by Quartz (JobStore init failure, cluster check failure) is wrapped in this unchecked exception, which aborts application startup.

Source

Thrown at extensions/quartz/runtime/src/main/java/io/quarkus/quartz/runtime/QuartzSchedulerImpl.java:527

                    } catch (SchedulerException e) {
                        throw new IllegalStateException("Unable to unschedule job with identity: " + identity);
                    }
                    return trigger;
                }
            }
        }
        return null;
    }

    // Use Interceptor.Priority.PLATFORM_BEFORE to start the scheduler before regular StartupEvent observers
    void start(@Observes @Priority(Interceptor.Priority.PLATFORM_BEFORE) StartupEvent startupEvent) {
        if (scheduler == null || startHalted) {
            return;
        }
        try {
            scheduler.start();
        } catch (SchedulerException e) {
            throw new IllegalStateException("Unable to start Scheduler", e);
        }
    }

    /**
     * Need to gracefully shut down the scheduler making sure that all triggers have been
     * released before datasource shutdown.
     *
     * @param event ignored
     */
    void destroy(@Observes(notifyObserver = Reception.IF_EXISTS) @BeforeDestroyed(ApplicationScoped.class) Object event) {
        if (scheduler != null) {
            try {
                if (shutdownWaitTime.isZero()) {
                    scheduler.shutdown(false);
                } else {
                    CompletableFuture.supplyAsync(new Supplier<>() {
                        @Override
                        public Void get() {

View on GitHub (pinned to e1c734241f)

Solutions

  1. Read the cause SchedulerException in the startup stack trace
  2. Validate the datasource (URL, credentials, network) if using the jdbc store
  3. Ensure Quartz tables exist (run the Quartz DDL scripts for your DB)
  4. For clustered mode, verify quarkus.quartz.cluster-checkin-interval and that node names/config match across nodes

Example fix

// before (application.properties)
# quarkus.quartz.store-type=jdbc  (DB missing tables)
// after
quarkus.quartz.store-type=db
# or create tables:
# CREATE TABLE QRTZ_JOB_DETAILS (...);  -- from Quartz DDL
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-startup: validate datasource for jdbc store
@Observes StartupEvent e -> { /* ensure DB reachable before quartz starts */ }

Try / catch

// This aborts startup by design; fix config rather than catch.
// In tests, catch assertion:
try {
    app.start();
} catch (IllegalStateException e) {
    assertThat(e).hasMessageContaining("Unable to start Scheduler");
}

Prevention

When it happens

Trigger: Application startup with a Quartz scheduler configured but its JobStore failing to initialize — JDBC store DB unreachable, cluster lock acquisition failing, misconfigured quartz properties (instanceId, misfire threshold).

Common situations: quarkus.quartz.store-type=jdbc with a datasource that is down or missing Quartz tables; clustered mode with mismatched instance names or clock skew; wrong driver/credentials in the datasource config.

Related errors

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