Quartz.NET Job Listeners: Track Runs, Failures, Vetoes, and Misfires
Contents
A Quartz.NET job listener sees every run that actually starts: JobToBeExecuted before the job, JobWasExecuted after it with a JobExecutionException if it failed, and JobExecutionVetoed if a trigger listener blocked it. A trigger listener adds the veto decision and misfire notices, and a scheduler listener reports standby, shutdown, and scheduler errors. None of them can tell you about a run that never fired, because they live in the process that didn't fire it.
This guide covers Quartz.NET 3.x (3.13 and later), with source links to JobRunShell.cs at v3.13.0, checked November 16, 2026. Quartz.NET 4 returns ValueTask from these callbacks and changes the scheduler listener's signatures; the differences are noted where they matter. For basic logging listeners and health checks, see Quartz.NET monitoring.
The Order Quartz Calls Listeners#
Every run goes through JobRunShell, which notifies listeners in a fixed order around your job:
| Step | Call | Who receives it | Notes |
|---|---|---|---|
| 1 | TriggerFired |
Trigger listeners | The trigger fired; the job hasn't started |
| 2 | VetoJobExecution |
Trigger listeners | Any listener returning true vetoes the run |
| 3a | JobExecutionVetoed |
Job listeners | Only on a veto; the run ends here |
| 3b | JobToBeExecuted |
Job listeners | Only if nobody vetoed |
| 4 | IJob.Execute |
Your job | JobRunTime measures only this step |
| 5 | JobWasExecuted |
Job listeners | With null, or the run's JobExecutionException |
| 6 | TriggerComplete |
Trigger listeners | With the trigger's SchedulerInstruction for this run |
On a veto, Execute, JobWasExecuted, and TriggerComplete never happen. A listener that records "started" in TriggerFired and "finished" in TriggerComplete will therefore leave vetoed runs open forever; record the start in JobToBeExecuted instead.
Misfires take a different path. TriggerMisfired isn't part of a run at all. The job store calls it when it finds a trigger whose fire time passed by more than the misfire threshold, before applying the trigger's misfire instruction (misfire instructions).
What JobWasExecuted Receives#
The second argument of JobWasExecuted is how a listener learns the result, and it isn't always what you'd expect:
| What the job did | jobException |
|---|---|
| Returned normally | null |
Threw JobExecutionException |
That exception, with its flags |
| Threw anything else | A new JobExecutionException wrapping a SchedulerException("Job threw an unhandled exception."), which wraps your exception |
Threw OperationCanceledException after cancellation |
null, logged as "Job ... was cancelled" |
Two consequences. To log the real error, unwrap: the original is jobException.InnerException?.InnerException for a plain exception, and jobException.InnerException for a JobExecutionException you constructed around a cause. And in 3.x a cancelled run, such as one interrupted by shutdown, looks like a success to every listener. Quartz.NET 4.4 changed this: the run is recorded as Cancelled, not as a success.
The Flags on JobExecutionException#
A job can steer what happens next by throwing JobExecutionException with flags set:
RefireImmediatelyre-runs the job at once on the same thread.JobRunShellloops back to the beginning, soTriggerFired,VetoJobExecution, andJobToBeExecutedall run again, andcontext.RefireCountgoes up by one. A listener sees a failure followed by a fresh start for the same fire time.UnscheduleFiringTriggerremoves the trigger that fired this run.UnscheduleAllTriggersremoves every trigger for the job.
The last two are the quiet ones. A job that unschedules its own trigger after a bad run never fires again, and no listener is told after that, because there are no more runs. The wrapper Quartz builds for a plain exception sets none of these flags.
A Listener That Records Every Outcome#
This listener records the outcomes from the tables above, including refires, cancellations, and vetoes. It's written for Quartz.NET 3.x:
using Microsoft.Extensions.Logging;
using Quartz;
public sealed class RunOutcomeListener : IJobListener
{
private readonly ILogger<RunOutcomeListener> _logger;
public RunOutcomeListener(ILogger<RunOutcomeListener> logger) => _logger = logger;
public string Name => "RunOutcomeListener";
public Task JobToBeExecuted(IJobExecutionContext context, CancellationToken cancellationToken = default)
{
try
{
_logger.LogInformation(
"Job {JobKey} starting, fire instance {FireId}, refire {RefireCount}, scheduled {Scheduled:u}",
context.JobDetail.Key, context.FireInstanceId, context.RefireCount, context.ScheduledFireTimeUtc);
}
catch (Exception error)
{
// A listener that throws here stops the job from running.
Console.Error.WriteLine($"RunOutcomeListener failed: {error.GetType().Name}");
}
return Task.CompletedTask;
}
public Task JobExecutionVetoed(IJobExecutionContext context, CancellationToken cancellationToken = default)
{
try
{
_logger.LogWarning("Job {JobKey} vetoed by trigger {TriggerKey}", context.JobDetail.Key, context.Trigger.Key);
}
catch (Exception error)
{
Console.Error.WriteLine($"RunOutcomeListener failed: {error.GetType().Name}");
}
return Task.CompletedTask;
}
public Task JobWasExecuted(IJobExecutionContext context, JobExecutionException? jobException,
CancellationToken cancellationToken = default)
{
try
{
if (jobException is null && context.CancellationToken.IsCancellationRequested)
{
// In 3.x a cancelled run arrives with no exception.
_logger.LogWarning("Job {JobKey} was cancelled after {Duration}", context.JobDetail.Key, context.JobRunTime);
}
else if (jobException is null)
{
_logger.LogInformation("Job {JobKey} succeeded in {Duration}", context.JobDetail.Key, context.JobRunTime);
}
else
{
var cause = jobException.InnerException is SchedulerException wrapped
? wrapped.InnerException ?? wrapped
: jobException.InnerException ?? jobException;
_logger.LogError(cause,
"Job {JobKey} failed after {Duration}; refire {Refire}, unschedule trigger {UnscheduleOne}, unschedule all {UnscheduleAll}",
context.JobDetail.Key, context.JobRunTime, jobException.RefireImmediately,
jobException.UnscheduleFiringTrigger, jobException.UnscheduleAllTriggers);
}
}
catch (Exception error)
{
Console.Error.WriteLine($"RunOutcomeListener failed: {error.GetType().Name}");
}
return Task.CompletedTask;
}
}FireInstanceId is the same across refires of one fire, so it's the identifier to pair a start with its finish.
Vetoes: Skipping a Run on Purpose#
A trigger listener's VetoJobExecution is the supported way to skip a run without touching the job, for example while a maintenance flag is set. The run is recorded as complete for the trigger, and the next fire time is calculated as usual:
using Microsoft.Extensions.Logging;
using Quartz;
using Quartz.Listener;
public sealed class MaintenanceVetoListener : TriggerListenerSupport
{
private readonly ILogger<MaintenanceVetoListener> _logger;
public MaintenanceVetoListener(ILogger<MaintenanceVetoListener> logger) => _logger = logger;
public override string Name => "MaintenanceVetoListener";
public override Task<bool> VetoJobExecution(ITrigger trigger, IJobExecutionContext context,
CancellationToken cancellationToken = default)
{
var inMaintenance = File.Exists("/etc/myapp/maintenance");
return Task.FromResult(inMaintenance);
}
public override Task TriggerMisfired(ITrigger trigger, CancellationToken cancellationToken = default)
{
_logger.LogWarning("Trigger {TriggerKey} misfired; instruction {Instruction}",
trigger.Key, trigger.MisfireInstruction);
return Task.CompletedTask;
}
}Log every veto. A vetoed run looks like a missed run from outside, and a veto rule that's stuck on, such as a flag file nobody removed, stops a job as completely as a dead scheduler does.
Registering Listeners#
Listeners aren't stored in the job store with jobs and triggers. The listener tutorial says to register them again every time the application starts, so registration belongs in startup code, not in a one-time setup script.
With ListenerManager#
On a scheduler you build yourself, add listeners through scheduler.ListenerManager with a matcher that picks which jobs or triggers they hear about:
using Microsoft.Extensions.Logging;
using Quartz;
using Quartz.Impl;
using Quartz.Impl.Matchers;
using var loggerFactory = LoggerFactory.Create(logging => logging.AddConsole());
var scheduler = await new StdSchedulerFactory().GetScheduler();
// Every job.
scheduler.ListenerManager.AddJobListener(
new RunOutcomeListener(loggerFactory.CreateLogger<RunOutcomeListener>()),
GroupMatcher<JobKey>.AnyGroup());
// Only the billing and reports groups.
scheduler.ListenerManager.AddTriggerListener(
new MaintenanceVetoListener(loggerFactory.CreateLogger<MaintenanceVetoListener>()),
OrMatcher<TriggerKey>.Or(
GroupMatcher<TriggerKey>.GroupEquals("billing"),
GroupMatcher<TriggerKey>.GroupEquals("reports")));
await scheduler.Start();KeyMatcher<JobKey>.KeyEquals(new JobKey("nightly-report", "reports")) narrows a listener to one job. Add listeners before Start(), so the first runs after startup are covered.
With AddQuartz and Dependency Injection#
With the Microsoft DI integration, AddJobListener<T> and AddTriggerListener<T> take the same matchers, and the listener is resolved from the container, so constructor injection works:
using Quartz;
using Quartz.Impl.Matchers;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddQuartz(q =>
{
q.AddJobListener<RunOutcomeListener>(GroupMatcher<JobKey>.AnyGroup());
q.AddTriggerListener<MaintenanceVetoListener>(GroupMatcher<TriggerKey>.GroupEquals("reports"));
});
builder.Services.AddQuartzHostedService(options => options.WaitForJobsToComplete = true);
builder.Build().Run();In Quartz.NET 4 the same calls exist in the main Quartz package, the callbacks return ValueTask, and every ISchedulerListener member takes the IScheduler as its first parameter. A listener method left with its 3.x signature still compiles there, because every listener member has a default implementation, and Quartz refuses the listener when it is registered; upgrading to Quartz.NET 4 covers the change.
Listener Rules That Keep Jobs Running#
Listener code runs inside the job's execution, on the same worker thread, which gives it more power over the job than it looks like it should have.
- Never throw. The tutorial is explicit that listeners should catch their own errors.
JobRunShellshows why: if notifying job listeners before execution fails, the job doesn't run, and if notifying them afterward fails, the trigger's completion handling is skipped. Wrap every callback intry/catch, as above. - Keep it fast.
JobToBeExecuteddelays the job andJobWasExecutedholds the worker thread, which counts against the thread pool (10 threads by default). A listener that calls an HTTP endpoint needs a short timeout; five seconds is a reasonable cap. - Don't change job behavior. A listener that "fixes" a failure by swallowing it, or retries work itself, makes the job's result depend on monitoring code. Observe and record; let the job and its triggers decide.
- Names identify listeners. Each listener's
Nameis how theListenerManagertracks it, so give each listener its own name.
What In-Process Listeners Can't See#
A listener is notified when something happens in this scheduler. Most production failures are things that didn't happen:
| Failure | What listeners see |
|---|---|
| The host process is down or never started | Nothing; no listener is running |
| The scheduler is in standby | One SchedulerInStandbyMode, then silence |
A trigger is paused, or in the ERROR state |
Nothing per missed fire |
| A job unscheduled its own trigger | The last failure, then silence |
| A fire time passed during downtime (persistent store) | TriggerMisfired after restart, possibly hours late |
| A fire time passed during downtime (RAM store) | Nothing; triggers are re-created from code at startup |
| A clustered node owns the trigger | Only that node's listeners hear about the run |
| A veto rule stays on | JobExecutionVetoed on every fire, with no alert |
Each of these looks the same from outside: the work didn't get done and nothing reported an error. A listener can record what happened; detecting what didn't happen needs something outside the process that knows the schedule and notices when a run doesn't arrive.
Let CronRadar.Quartz Register the Listener#
CronRadar.Quartz 0.2.0 does the registration for you. After you schedule your jobs, one call registers a job listener for every job and declares each job's schedule to CronRadar:
dotnet add package CronRadar.Quartzusing CronRadar.Quartz;
using Quartz;
using Quartz.Impl;
var scheduler = await new StdSchedulerFactory().GetScheduler();
var job = JobBuilder.Create<NightlyReportJob>().WithIdentity("nightly-report", "reports").Build();
var trigger = TriggerBuilder.Create()
.WithIdentity("nightly-report-trigger", "reports")
.WithCronSchedule("0 0 2 * * ?")
.Build();
await scheduler.ScheduleJob(job, trigger);
// Reads CRONRADAR_API_KEY from the environment.
await scheduler.MonitorAll();
await scheduler.Start();
public sealed class NightlyReportJob : IJob
{
public Task Execute(IJobExecutionContext context)
{
Console.WriteLine("Generating the nightly report");
return Task.CompletedTask;
}
}With AddQuartz(), call MonitorAll() from an IHostedService after the scheduler starts, as the Quartz integration guide shows. The package uses Quartz.NET 4 on .NET 10 and 3.13 or later on earlier frameworks.
Its listener reports a start from JobToBeExecuted and a completion or failure from JobWasExecuted, catches its own errors so it can't stop a job, and gives each job a monitor keyed on its JobKey. Because CronRadar knows each trigger's cron schedule, it also covers the silent rows in the table above: when no start arrives by the expected time plus the grace period (60 seconds by default), the monitor goes from warning to critical and alerts by email, Slack, webhook, Discord, or PagerDuty. That alert comes from CronRadar, so it fires when the host is what's down. A reported failure alerts immediately, and a start with no finish is flagged as stuck.
How the listener behaviors above show up:
- Vetoes: a vetoed run sends nothing, so on a scheduled fire it counts as a missed run and alerts after the grace period. Opt a job out with
[SkipMonitor]on its class if vetoes are routine for it. - Refires: each attempt reports, so
RefireImmediatelyproduces a failure followed by a new start. - Cancellation in 3.x: a cancelled run reaches the listener with no exception and is reported as complete.
- Schedules: each cron trigger is translated to five-field cron. One with no five-field form, such as a non-zero seconds field, logs a warning and stays unmonitored, and hours aren't converted between time zones; CronRadar evaluates schedules in the application's time zone, UTC if unset.
Override a job's key with [CronRadar("key")] on the IJob class. Use a separate CronRadar application and key per environment.
Frequently Asked Questions#
What is the difference between a job listener and a trigger listener in Quartz.NET?#
A job listener hears about a job's execution: before it runs, after it runs with any exception, and when it's vetoed. A trigger listener hears about the trigger: when it fires, whether to veto the run, when it misfires, and when the run completes with the trigger's instruction. Use a job listener to record results and a trigger listener to veto runs or watch misfires.
Why doesn't JobWasExecuted get called for some runs?#
Either the run was vetoed, in which case job listeners get JobExecutionVetoed instead, or the run never started because the scheduler was down, in standby, or the trigger was paused. It can also be skipped if a job listener threw an exception in JobToBeExecuted, which stops the job from running.
How do I get the original exception in a Quartz.NET job listener?#
If the job threw a plain exception, Quartz wraps it twice: JobWasExecuted receives a JobExecutionException whose inner exception is a SchedulerException whose inner exception is yours. If the job threw its own JobExecutionException with a cause, the cause is its InnerException.
Do Quartz.NET listeners survive a restart?#
No. Listeners aren't saved in the job store, even with a database store that persists jobs and triggers. Register them in startup code every time the application starts, before calling Start().
Can a job listener detect a missed Quartz.NET run?#
Not reliably. If the process is down, no listener runs. With a persistent store, a missed fire time shows up as TriggerMisfired after the scheduler restarts, which may be hours later; with the RAM store it doesn't show up at all. Detecting a run that never happened needs a check outside the process that knows when each run is due.
Put this guide to work
Connect your Quartz.NET job to monitoring
Follow the current integration guide, check the release limitations, and verify a real run and alert delivery.
NuGet installs CronRadar.Quartz 0.2.1, which uses Quartz.NET 4 on .NET 10 and Quartz.NET 3.13 or later on earlier frameworks. It translates cron triggers to five-field schedules. An expression with no five-field form logs a warning and stays unmonitored, and hours are not converted between time zones. Discovered monitors start with a 60-second grace period unless the code sets another; a grace period or schedule edited in the dashboard stays until the code declares a different value.