# Quartz.NET Job Listeners: Track Runs, Failures, Vetoes, and Misfires

By Dan Ochoa · Published 2026-11-16 · Updated 2026-11-16
Canonical: https://cronradar.com/blog/quartz-net-job-listeners

> How Quartz.NET IJobListener, ITriggerListener and ISchedulerListener report runs, JobExecutionException, vetoes and misfires, registration, and their limits.

**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](https://github.com/quartznet/quartznet/blob/v3.13.0/src/Quartz/Core/JobRunShell.cs), 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](https://cronradar.com/blog/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](https://cronradar.com/blog/quartz-net-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:

- **`RefireImmediately`** re-runs the job at once on the same thread. `JobRunShell` loops back to the beginning, so `TriggerFired`, `VetoJobExecution`, and `JobToBeExecuted` all run again, and `context.RefireCount` goes up by one. A listener sees a failure followed by a fresh start for the same fire time.
- **`UnscheduleFiringTrigger`** removes the trigger that fired this run.
- **`UnscheduleAllTriggers`** removes 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:

```csharp
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:

```csharp
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](https://www.quartz-scheduler.net/documentation/quartz-3.x/tutorial/trigger-and-job-listeners.html) 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:

```csharp
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:

```csharp
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](https://cronradar.com/blog/quartz-net-4-upgrade) 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. `JobRunShell` shows 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 in `try`/`catch`, as above.
- **Keep it fast.** `JobToBeExecuted` delays the job and `JobWasExecuted` holds 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 `Name` is how the `ListenerManager` tracks 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:

```bash
dotnet add package CronRadar.Quartz
```

```csharp
using 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](https://docs.cronradar.com/integrations/quartz) 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 `RefireImmediately` produces 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.
