Quarkus Scheduler and Quartz for Periodic and Cron Jobs
Run periodic and cron jobs in Quarkus with the Scheduler extension, handle concurrency and identity, and switch to Quartz for clustered, persistent jobs.

Periodic work in a Quarkus application starts with one extension and one annotation, and it stops being simple at the point where you run two instances. The built-in scheduler is in memory: every instance runs every job. That is exactly right for a cache refresh and exactly wrong for "send the nightly invoices". This post covers the built-in scheduler, the overlap and thread behaviour that cause the first surprises, the move to Quartz for clustered jobs, programmatic scheduling and how to test a schedule. It uses Quarkus 3 and JDK 25.
The simple scheduler
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-scheduler</artifactId>
</dependency>@ApplicationScoped
public class Cleanup {
@Inject SessionRepository sessions;
@Scheduled(every = "10m", delayed = "30s", identity = "session-cleanup")
void purgeExpired() {
sessions.deleteExpired();
}
@Scheduled(cron = "{cleanup.report.cron}")
void report() {
// nightly summary
}
}every takes a duration such as 30s, 10m or 1h. cron takes a Quartz-style expression with seconds (0 0 2 * * ? is 02:00 every day), and a value in braces is read from configuration, so operators can change a schedule per environment without a rebuild: cleanup.report.cron=0 0 2 * * ? in application.properties, with a %dev or %test override to disable it. delayed postpones the first run, which avoids a burst of work at startup while the application warms up. identity names the job, which matters for metrics and for the programmatic API.
A scheduled method must be non-private, return void or a CompletionStage/Uni, and take no parameters, or a single ScheduledExecution parameter that exposes the fire time and scheduled time. It lives on a CDI bean, and the bean must not be @RequestScoped.
Overlap and delays
By default, if a run takes longer than the interval, the next trigger starts a second run in parallel. For a job that is not safe to run twice at once, that is a bug waiting for a slow day. Set the policy:
@Scheduled(every = "1m", concurrentExecution = Scheduled.ConcurrentExecution.SKIP)
void syncInventory() { /* may take longer than a minute */ }SKIP skips a trigger while the previous run is still going; PROHIBIT is the default name for the same idea in some versions of the docs, and PROCEED is the overlap behaviour. Check the enum in your Quarkus version. A skip is silent, so log at the start and end of long jobs, and alert when a job has not completed for several intervals.
Missed triggers while the application is down are not replayed by the in-memory scheduler. If the service restarts at 01:59 and starts at 02:05, the 02:00 job does not run. For a job that must run once per day regardless, record the last success in a table and have the job check "has today's run happened" every few minutes, which survives restarts.
What thread runs it
Scheduled methods run on a worker thread by default, not on the event loop, so blocking calls such as JDBC are allowed. A method returning Uni runs on the event loop and must not block. Annotate with @Blocking or @NonBlocking to be explicit. Virtual threads are available with @RunOnVirtualThread on JDK 21 and later, which suits blocking I/O jobs. Because the thread is not a request thread, request-scoped beans and the transaction context of a caller do not exist. A job that touches the database needs its own transaction:
@Scheduled(cron = "0 0 3 * * ?")
@Transactional
void archiveOrders() { orders.archiveOlderThan(Duration.ofDays(365)); }Without @Transactional (or a call to a bean method that has it), a Panache write fails with a TransactionRequiredException, the same failure as in Spring, explained in the transaction fix. The thread pools behind it are standard pools; their sizing logic is in using thread pools properly.
The in-memory limit
Run three replicas of this application and report() runs three times at 02:00, once per replica. The simple scheduler has no knowledge of other instances. For jobs where duplication is harmless or desired, such as refreshing a local cache, that is the right behaviour. For jobs that send emails, charge cards or write totals, it is a defect, and the fix is clustering support.
The scheduler also has no persistence. A job's schedule is defined in code, so there is no stored state to lose, but there is also no history, no manual trigger from a console and no way to see what ran last night, except from your logs.
Quartz for clusters
The Quartz extension adds a persistent job store. With a JDBC store shared by all instances, Quartz uses row locks to ensure that each trigger fires on exactly one node.
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-quartz</artifactId>
</dependency>quarkus.quartz.clustered=true
quarkus.quartz.store-type=jdbc-cmt
quarkus.quartz.misfire-policy=fire-now
quarkus.datasource.db-kind=postgresqlThe @Scheduled annotation works unchanged; the extension swaps the engine. With clustered=true and a JDBC store, each job runs once per trigger across the cluster, and a node that dies releases its work for another. The Quartz tables must exist: use the SQL script for your database from the Quartz distribution through your migration tool (Flyway or Liquibase), and set quarkus.flyway.migrate-at-start accordingly; Quarkus can also create them in dev mode through quarkus.quartz.store-type with a Dev Services database. misfire-policy decides what happens to triggers missed while all nodes were down: fire-now runs once on recovery. Clocks matter in a cluster. Nodes with drifting clocks cause misfires, so run time synchronisation. Quartz adds database load and a few tables to maintain, and the instance that starts first creates the scheduler record. The details are in the Quartz guide.
For jobs that are really workflows with steps, retries and waiting, a durable workflow engine fits better than a cron expression; see Temporal.
Programmatic jobs
Jobs defined at run time, from a database row or a user action, use the Scheduler bean:
@Inject Scheduler scheduler;
void scheduleReminder(String id, Instant at) {
scheduler.newJob("reminder-" + id)
.setCron(CronUtils.toCron(at))
.setTask(execution -> reminders.send(id))
.schedule();
}A programmatic job in the simple scheduler is lost on restart, so rebuild jobs from the database at startup. With Quartz, Scheduler.newJob creates a job in the store if you use the QuartzScheduler API's persistent option; check the guide for the supported combination in your version. Remove jobs with scheduler.unscheduleJob(identity).
Test the schedule
Test the work, not the clock. Call the method directly in a @QuarkusTest, and disable triggers in the test profile so a real schedule does not fire in the middle of a test: %test.quarkus.scheduler.enabled=false, or point the cron at a date that never occurs. Verify the cron expression separately by parsing it with the Quartz CronExpression class and asserting the next fire time. Background on testing asynchronous code is in testing async code and schedulers and the profile mechanism in Quarkus configuration profiles.
Where this does not apply
If the jobs belong to the infrastructure, a Kubernetes CronJob that starts a container for each run is simpler to operate and scales to zero between runs, at the price of a startup per execution, where native images help. The scheduler reference is the Quarkus scheduler guide.


