Misfires

A trigger is misfired when its next fire time lies further in the past than the job store’s misfireThreshold and it is still waiting to fire. Two details matter: the lateness is measured against the threshold (a trigger that is a little late is not a misfire, it just fires late), and a trigger with the IGNORE_MISFIRE_POLICY instruction is never evaluated at all. In the source this is the condition nextFireTime < now - misfireThreshold and misfireInstruction != -1, checked by RAMJobStore.applyMisfire and by the SQL of JobStoreSupport (SELECT_MISFIRED_TRIGGERS_IN_STATE excludes triggers whose MISFIRE_INSTR is -1).

A stall shorter than the threshold is not a misfire. The trigger fires as soon as a thread is free and then catches up one tick at a time, without any misfire notification. Measured with the Spring Boot RAM default of 5000 ms and a 3 s standby on a trigger that fires every second:

Source: Quartz documentation: Lesson 4, More About Triggers and the RAMJobStore source at v2.5.2. Run on Quartz 2.5.2 with a plain StdSchedulerFactory and a RAMJobStore: the three ticks that fell due during the stall (3.2, 4.2 and 5.2 s) all ran at 5.5 s, and no TriggerListener.triggerMisfired callback was made.

The same stall with a threshold of 1000 ms is a misfire, and then the instruction decides what happens, see Every instruction, measured.

Where the check runs depends on the job store, and that is why a job store without a background thread (the RAM store) detects misfires later than a JDBC store.

Source: Quartz documentation: Lesson 4, More About Triggers and the JobStoreSupport source at v2.5.2.

org.quartz.jobStore.misfireThreshold is the number of milliseconds a trigger may be late before it counts as misfired. It must be at least 1 (setMisfireThreshold throws IllegalArgumentException below that, in both stores). The default is where the official documentation and the code disagree. The Quartz configuration pages for the RAM store and for JobStoreTX both document 60000 (60 seconds). The 2.5.2 source and a run on Spring Boot 4.1.1 say otherwise:

So a Spring Boot application that keeps the default in-memory store tolerates 5 seconds of lateness, and the same application moved to JDBC tolerates 60 seconds. Set it explicitly if the difference matters. The value is a trade-off: too low and a garbage-collection pause or a short deployment counts as an outage and triggers the instruction; too high and a real outage is treated as lateness, and every missed tick is replayed one after the other (see the IGNORE_MISFIRE_POLICY behaviour below). A threshold of about one minute is a common starting point for a JDBC store; it must be well below the interval of your shortest trigger, otherwise that trigger never counts as misfired and always catches up.

Source: Spring Boot: Quartz Scheduler and Quartz documentation: Configure JDBCJobStoreTX. Run: spring.quartz.properties.org.quartz.jobStore.misfireThreshold=60000 took effect on Boot’s memory store (measured threshold 60000).

Every trigger has an integer misfire instruction, set on its schedule builder. There are two instructions common to all types and a set specific to each type, with the constants declared on the type’s interface. MISFIRE_INSTRUCTION_SMART_POLICY (0) is the default of every schedule builder.

The builder method is the readable way; the underlying integer is what is stored in the MISFIRE_INSTR column of QRTZ_TRIGGERS. With the Spring factory beans the same constant is chosen by name: SimpleTriggerFactoryBean and CronTriggerFactoryBean have setMisfireInstruction(int) and setMisfireInstructionName(String), which takes the name of a constant on the trigger interface and rejects an unknown name when the bean is created.

Source: Quartz documentation: Lesson 5, SimpleTrigger and Spring Framework: Task Execution and Scheduling. Compiled and run against Quartz 2.5.2 and Spring Framework 7.0.9; getMisfireInstruction() returned 4 for the built trigger.

To see every instruction work, one scheduler held a RAMJobStore with misfireThreshold=1000 and a set of triggers that all fire every second (the simple ones forever, and with a repeat count of 9, that is ten firings). The scheduler was put in standby (Scheduler.standby()) from t=2.5 s to t=7.5 s, a five second outage during which five ticks fell due, and then started again. A recording job logged the time of every run.

Source: Quartz documentation: Lesson 4, More About Triggers and Quartz Javadoc: SimpleTrigger. Run on Quartz 2.5.2: the fire times behind the diagram are in the tables below.

The test is a plain Quartz scheduler, so it shows the behaviour of the trigger types and instructions rather than of Spring Boot:

Source: Quartz documentation: Lesson 5, SimpleTrigger and Quartz documentation: Lesson 6, CronTrigger. Run on Quartz 2.5.2 with the full matrix of 27 triggers; the results follow.

Three consequences are worth keeping in mind. First, the triggerMisfired callback was invoked exactly once for every trigger that was evaluated, and never for those with IGNORE_MISFIRE_POLICY: that policy is invisible to listeners and metrics. Second, for SimpleTrigger, the instructions with NOW re-anchor the schedule on the recovery time (the whole grid slides), while the NEXT instructions keep the original grid. Third, calendar-interval and daily-time-interval triggers keep their grid after FIRE_ONCE_NOW (the run at 7.5 s is extra and the next one is back on the grid) because their next fire time is always computed from the start time, which the instruction does not move.

The RAM store forgets its triggers when the JVM stops, so only a persistent store can recover from a real outage. To see that, the same style of test used an H2 database through JobStoreTX (misfireThreshold=2000) with the Bookshelf triggers compressed to seconds: the cache refresh every second with NextWithRemainingCount, the overdue reminders and the weekly report every two seconds with FireAndProceed and the smart policy, the retention cleanup every two seconds with DoNothing, and a one-shot member reminder due at 4 s. The first scheduler was shut down at t=2.5 s, the application stayed down until t=9.3 s, and a second scheduler was started against the same database.

The log of the second scheduler shows the start-up handling of all five triggers in one pass, regardless of maxMisfiresToHandleAtATime:

Source: Quartz documentation: Lesson 9, Job Stores and the JobStoreSupport source at v2.5.2. Run on Quartz 2.5.2 with H2 2.4.240 and HikariCP (org.quartz.dataSource.ds.provider=hikaricp); Spring Boot’s own JDBC store runs the same code path (LocalDataSourceJobStore extends JobStoreCMT). Persistent stores themselves are on Job Stores & Persistence.

Two Spring Boot details decide whether this recovery happens at all. With a JDBC store Boot registers a Trigger bean only if no trigger with that key is stored yet, so the stored NEXT_FIRE_TIME and misfire instruction from the previous run stay in force (and a changed instruction in the code is not applied to an already stored trigger). With spring.quartz.overwrite-existing-jobs=true Boot instead calls rescheduleJob, which replaces the stored trigger with the bean and computes a fresh first fire time: the missed tick is gone and no misfire is ever detected. That setting is a way to publish a changed schedule, not a way to recover from an outage.

Source: Spring Boot: Quartz Scheduler. Read from SchedulerAccessor.addTriggerToScheduler (Spring Framework 7.0.9) and QuartzScheduler.rescheduleJob (Quartz 2.5.2, which calls computeFirstFireTime on the replacement trigger).

org.quartz.jobStore.maxMisfiresToHandleAtATime (default 20, JDBC stores only) bounds how many misfired triggers the MisfireHandler processes in one pass. The reason is the lock: each pass holds the TRIGGER_ACCESS row lock and rewrites the misfired triggers, so handling a great many at once can delay the firing (and completion) of other triggers that are not misfired (the Quartz configuration page recommends staying below a couple of dozen). If more than the limit are misfired, the handler works through them in successive batches 50 ms apart and then returns to its normal interval of about misfireThreshold.

The pass is easy to see with a small limit. One worker thread was held busy for 6 seconds by a job while six cron triggers (with DoNothing) fell due; with maxMisfiresToHandleAtATime=2 the MisfireHandler logged:

Source: Quartz documentation: Configure JDBCJobStoreTX. Run on Quartz 2.5.2 with H2 and a one-thread pool. The two later passes about 2 s afterwards show the cron triggers misfiring again while the thread was still busy.

The limit does not apply in two places. A non-clustered scheduler handles every misfired trigger once when it starts (the log line "Handling 5 trigger(s)" above), and the RAM store has no such property. A related property, org.quartz.jobStore.doubleCheckLockMisfireHandler (default true), makes the handler count misfired triggers before it takes the lock, so an idle system does not pay for the lock every pass; it should be set to false only if there are misfired triggers nearly all the time.

A practical corollary: if the restart of an application would make dozens of triggers fire at the same time (every cron trigger on the default FIRE_ONCE_NOW), the burst is not smoothed by the limit, it is limited only by the worker thread pool. Choose DoNothing for triggers whose late run has no value, or stagger their schedules.

The Quartz distribution ships fifteen examples; Example 5 (org.quartz.examples.example5.MisfireExample) is the misfire demonstration. Two triggers with identical schedules fire a job every 3 seconds, but the job takes 10 seconds and must not run concurrently, so by the time it finishes the triggers have misfired (the example’s scheduler sets misfireThreshold to 1000 and uses two threads). One trigger keeps the smart policy; the other uses RESCHEDULE_NOW_WITH_EXISTING_REPEAT_COUNT. The version below has the same shape (a plain scheduler with a RAMJobStore, a threshold of 1000 ms, two threads and a ten second job) and starts half a second after the scheduler.

Source: Quartz source: example5/MisfireExample and Quartz documentation: Examples. Run on Quartz 2.5.2 for 45 seconds; the original also carries @PersistJobDataAfterExecution on its job, which does not change the misfire behaviour.

The behaviour the example makes visible is the back-pressure case: a trigger whose job takes longer than its interval can only fire when the job ends, and the instruction decides what that moment looks like. The smart policy keeps the original timetable and lets the job run less often than its interval; NOW makes the job run continuously. With IGNORE_MISFIRE_POLICY it is worse, as the next section shows.

When the instruction moves the fire time to "now" (FIRE_ONCE_NOW, FIRE_NOW, NOW), the job is a normal, late execution and the trigger no longer remembers which tick it missed. The JobExecutionContext reflects the rewritten trigger: getScheduledFireTime() is the moment of recovery, not the missed one. Measured with a cron trigger every second on FireAndProceed and a four second standby:

Source: Quartz Javadoc: JobExecutionContext and Quartz Javadoc: TriggerListener. Run on Quartz 2.5.2. In the first line the tick at 1214 ran on time; the TriggerListener.triggerMisfired callback saw the original next fire time (2214), and the late run’s scheduledFireTime (5529) is the recovery time.

Two design rules follow. A job must never compute its work period from getScheduledFireTime() ("the week that ends at the scheduled time") because after a misfire that is the wrong week; it should derive the period from the wall clock or, better, from the data it has already processed. And a job that runs after a misfire must be idempotent: it may run late, and with FIRE_ONCE_NOW it replaces several missed runs, so it has to catch up on everything outstanding, not only on "one tick of work". getPreviousFireTime() is a cheap way to know when it last ran.

The choice follows from one question per job: if the run did not happen on time, is a late run worth anything, and does one late run stand in for all the missed ones?

Source: Quartz documentation: Scheduling a Job and Spring Boot: Quartz Scheduler. Compiled against Quartz 2.5.2 and Spring Boot 4.1.1; the cache-refresh and overdue-reminder shapes are the ones the Bookshelf test project ran (the five jobs on a JDBC store, see Bookshelf triggers across a 6.8 second outage on the JDBC store (measured, seconds since the first start)).

A job written for a late run reads the clock, not the trigger, and reports how late it is:

Source: Quartz Javadoc: JobExecutionContext. Compiled against Quartz 2.5.2 and Spring Framework 7.0.9; the values of getScheduledFireTime() and getPreviousFireTime() after a misfire are the measured ones in the previous section.

The calendar and the misfire instruction interact. The NEXT and DO_NOTHING instructions pick the next tick that the trigger’s calendar includes, but FIRE_ONCE_NOW, FIRE_NOW and the NOW instructions set the next fire time to the current moment without asking the calendar (the Javadoc of the NOW instructions says so, and the source of the cron, calendar-interval and daily-time-interval triggers does the same). A late run after an outage can therefore land inside an excluded period, for example on a holiday. If that matters, prefer DoNothing, or have the job check the calendar itself (see Calendars).

Quartz does not expose misfires as a metric, but it tells every trigger listener. TriggerListener.triggerMisfired(Trigger) is called before the instruction is applied, with the trigger still holding the missed fire time. A listener registered through a SchedulerFactoryBeanCustomizer can count them with Micrometer (Spring Boot 4.1.1 registers no Quartz meters of its own, and a global trigger listener is the simplest way to add them):

Source: Quartz documentation: Lesson 7, TriggerListeners and JobListeners and Spring Boot: Quartz Scheduler. Compiled against Spring Boot 4.1.1; the same counter (quartz.trigger.misfired, one increment per misfire) was observed in an earlier run that provoked misfires with a misfireThreshold of 1000 and a short standby. Alerting on the counter, and the rest of the metrics, are on Observability; listeners in general are on Listeners & Plugins.

An instruction of IGNORE_MISFIRE_POLICY never reaches this callback, so a service that relies on the counter should not use it, or should alert on late executions instead (the difference between getFireTime() and getScheduledFireTime()).

Standard scheduling has no misfire concept. @Scheduled registers tasks with a TaskScheduler in memory; when the process is down nothing is remembered, so every tick during the outage is simply gone, and the first run after the restart is the next tick of the schedule. Within a running process the TaskScheduler has its own behaviour when its thread is busy, and it differs by task type. To measure it, a ThreadPoolTaskScheduler with one thread (Spring Boot’s default spring.task.scheduling.pool.size is 1) was given three tasks while a 3 second blocker held the only thread from t=2 s to t=5 s:

Source: Spring Framework: Task Execution and Scheduling and Spring Framework Javadoc: ThreadPoolTaskScheduler. Run on Spring Framework 7.0.9; the scheduler API is the one @Scheduled uses. The fire times follow in the table.

So the standard scheduler already behaves as if it had a misfire policy, but it is fixed by the task type, not configurable per task, not reported anywhere (there is no callback), and not persisted. The comparison in one table:

Source: Spring Framework: Task Execution and Scheduling and Quartz documentation: Lesson 4, More About Triggers. The @Scheduled and ShedLock side is on Scheduling & ShedLock and compared feature by feature on Standard Scheduling vs Quartz.