# Upgrading Quartz.NET 3.x to 4.x: What Changed and What to Test

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

> Upgrade Quartz.NET 3.x to 4.x: the .NET 10 requirement, package merges, ValueTask APIs, schema scripts, changed defaults, testing, and keeping jobs monitored.

**Quartz.NET 4 requires .NET 10, folds the DI, hosting, and System.Text.Json packages into the main `Quartz` package, changes most async members from `Task` to `ValueTask`, removes `StdSchedulerFactory` and binary serialization, and needs a database migration script if you use the ADO.NET job store.** The compiler finds most of the code changes. What it doesn't find are the changed defaults, such as the scheduler instance name and the misfire threshold, and those are what break a running deployment.

This guide covers moving from Quartz.NET 3.x to 4.x. Quartz.NET 4.7.3 was the latest release on NuGet when checked on November 16, 2026. The details come from the official [Quartz.NET 4.x migration guide](https://www.quartz-scheduler.net/documentation/quartz-4.x/migration-guide.html), which is long and has separate paths for running deployments, F# projects, and users of the 4.0 previews; read the section for your situation before you start.

## What 4.x Requires Before You Touch Code

| Area                 | Quartz.NET 3.x                                                                                 | Quartz.NET 4.x                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Target framework     | `netstandard2.0` and up, including .NET Framework                                              | .NET 10 or later only; no `netstandard2.0` build, no `.config` file support |
| Packages             | `Quartz` plus Extensions.DependencyInjection, Extensions.Hosting, Serialization.SystemTextJson | `Quartz` alone; those three are merged in                                   |
| Async signatures     | `Task`                                                                                         | `ValueTask` (`IJob.Execute`, `ScheduleJob`, listeners, job stores)          |
| Scheduler factory    | `StdSchedulerFactory`, `SchedulerBuilder`, `DirectSchedulerFactory`                            | Removed; `QuartzSchedulerBuilder` or `AddQuartz()`                          |
| Binary serialization | `BinaryObjectSerializer` available                                                             | Gone with .NET's `BinaryFormatter`; 4.x can't read binary blobs             |
| ADO.NET schema       | 3.x tables                                                                                     | Mandatory upgrade script; startup refuses a database that skipped it        |
| Remoting             | `quartz.scheduler.proxy*` and `exporter*`                                                      | Removed                                                                     |

Two consequences follow. The application moves to .NET 10 first, as its own change, and ships before Quartz changes. And if anything in your stack can't move, it pins you to 3.x: the guide says `MassTransit.Quartz` doesn't run on 4.x, and `Quartz.OpenTracing` has no 4.x release.

## Do Two Things While Still on 3.x

The guide's upgrade path for a running deployment has seven steps, and the first two happen before any 4.x node starts, because 4.x can't do them.

1. **Get off binary serialization.** If your job store holds job data written by `BinaryObjectSerializer`, 4.x can't read it, and the converter only exists in 3.x. The guide also notes that `BLOB_TRIGGERS.BLOB_DATA` can't be converted from 4.x. Follow its conversion steps on 3.x and confirm nothing binary is left.
2. **Audit stored cron expressions.** 4.x rejects some expressions that 3.x accepted and stored, and it fails when it reads such a row. List every cron trigger in the store, validate each expression against 4.x in a test project, and fix the ones it rejects while 3.x is still running them.

If you use the RAM job store, both steps reduce to "check the expressions in your code," since nothing is stored between runs.

## Migrate the Schema Before the Nodes

With the ADO.NET job store, run `schema_30_to_40_upgrade_<database>.sql` from the Quartz.NET repository before deploying any 4.x node. The guide says it's mandatory, safe to run twice, and safe while 3.x nodes are still firing. It makes four previously optional columns required (`MISFIRE_ORIG_FIRE_TIME`, `EXECUTION_GROUP`, `PREFERRED_NODE`, `PREFERRED_NODE_AUTO`), adds `RETRY_POLICY` and `RETRY_ATTEMPT` to `QRTZ_TRIGGERS`, and adds a `QRTZ_PAUSED_JOB_GRPS` table.

Three details to plan for:

- **4.x validates at startup.** It checks every table and column it reads and refuses to start against a database that skipped the migration. That's a loud failure, which is better than the alternative, but it means the script is part of the deploy, not a follow-up.
- **Paused job groups don't carry over.** Re-pause them on 4.x with `PauseJobGroups`.
- **The index script waits.** `schema_30_to_40_indexes_<database>.sql` is optional and affects performance only. Run it after the last 3.x node stops, because 3.x statements may still use the indexes it drops.

Later 4.x minor releases add their own migrations. The guide lists three required scripts for 4.6 and one for 4.7, so upgrading straight to the latest 4.x means running each in order.

During the rollout you can stop the cluster, or run 3.x and 4.0 nodes against the same tables. If you overlap them, the guide says not to let a 4.0 node write a calendar during that period.

## Swap the Packages

Remove `Quartz.Extensions.DependencyInjection`, `Quartz.Extensions.Hosting`, and `Quartz.Serialization.SystemTextJson`, and reference `Quartz` 4.x. Leaving any of the 3.x packages in place produces `CS0433` errors, because eight type names exist in both. Other replacements:

- `Quartz.Serialization.Json` (Newtonsoft) becomes `Quartz.Serialization.Newtonsoft`.
- The health check moved into `Quartz`. `Quartz.AspNetCore` is now needed only for the HTTP API or dashboard. Register the check with `AddHealthChecks().AddQuartz(...)` or `AddQuartzHealthChecks(...)`.
- `AddQuartzServer` is replaced by `AddQuartzHostedService`.
- For tracing, `OpenTelemetry.Instrumentation.Quartz` produces no spans on 4.x. Use `AddSource(QuartzInstrumentation.ActivitySourceName)` on your tracer instead.

## Fix What the Compiler Reports

Most code changes are mechanical. `IJob.Execute` returns `ValueTask` and takes the cancellation token as a parameter:

```csharp
using Quartz;

public sealed class NightlyReportJob : IJob
{
    public async ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken)
    {
        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
        Console.WriteLine($"Report generated for {context.ScheduledFireTimeUtc:u}");
    }
}
```

The rest of the list from the guide:

- **Scheduler state.** `IsStarted`, `InStandbyMode`, and `IsShutdown` are replaced by one `SchedulerStatus Status` property. The guide maps `IsStarted` to `Status is not SchedulerStatus.Created` and `IsShutdown` to `Status is SchedulerStatus.Shutdown`.
- **`ScheduleJob`** returns `ValueTask<DateTimeOffset>`, and the overloads that took a `CancellationToken` positionally are gone; pass `cancellationToken: token`.
- **`IScheduler` is `IAsyncDisposable`**, so `await using` can replace a `try`/`finally` that calls `Shutdown()`.
- **Hosted service hooks.** `QuartzHostedService.StartAsync` and `StopAsync` are no longer virtual. Override `StartingAsync`, `StartedAsync`, `StoppingAsync`, or `StoppedAsync`.
- **Options renames.** `AdoJobStoreOptions.UseProperties` is `StoreJobDataAsStrings`, `MakeThreadsDaemons` is `UseBackgroundThreads`, and `PerformSchemaValidation` is replaced by `SchemaProvisioning` (`Validate`, `None`, `CreateIfMissing`).
- **`JobDataMap` lookups.** The indexer throws `KeyNotFoundException` for a missing key, where 3.x returned `null`. This one compiles and fails at run time, so search for indexer reads that relied on `null`.
- **Configuration.** `quartz.config` file discovery is removed, and `QuartzOptions` no longer derives from `Dictionary<string, string?>`. Flat `quartz.*` keys still work, so configuration can be translated gradually.

With `StdSchedulerFactory` gone, a scheduler outside dependency injection comes from `QuartzSchedulerBuilder`:

```csharp
using Quartz;

var scheduler = await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler();
try
{
    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);
    await scheduler.Start();
    await Task.Delay(Timeout.Infinite);
}
finally
{
    await scheduler.Shutdown();
}
```

### Listeners Need the Most Care

Listener interfaces return `ValueTask` too, and every `ISchedulerListener` member now takes the `IScheduler` as its first parameter. The compiler won't point at the callbacks you have to change: every member of `IJobListener`, `ITriggerListener`, and `ISchedulerListener` has a default implementation, so a method left with its 3.x signature, such as `Task JobWasExecuted(...)` or `SchedulerStarted(CancellationToken)`, compiles but implements nothing. The migration guide says Quartz refuses such a listener when it is registered and names the member, so the failure shows at startup. Start the application once after the upgrade and read the registration errors before deploying.

Write 4.x scheduler listeners with the new signature:

```csharp
using Quartz;

public sealed class SchedulerShutdownLogger : ISchedulerListener
{
    public ValueTask SchedulerShuttingDown(IScheduler scheduler, CancellationToken cancellationToken = default)
    {
        Console.Error.WriteLine($"Quartz scheduler {scheduler.SchedulerName} is shutting down");
        return ValueTask.CompletedTask;
    }
}
```

Two listener behaviors changed as well. A start, standby, and shutdown now raise exactly `SchedulerStarting`, `SchedulerStarted`, `SchedulerInStandbyMode`, `SchedulerShuttingDown`, and `SchedulerShutdown`, and a shutdown no longer raises `SchedulerInStandbyMode` first, so a listener that treated standby as "stopped firing" must also handle `SchedulerShuttingDown`. Since 4.4, `context.Outcome` reads `Vetoed` inside `JobExecutionVetoed`. [Quartz.NET job listeners](https://cronradar.com/blog/quartz-net-job-listeners) covers listeners in depth.

## The Defaults That Change Silently

These don't produce compiler errors. Each one changes behavior for an application that never configured the setting.

| Setting                            | 3.x default              | 4.x default       | Why it matters                                                       |
| ---------------------------------- | ------------------------ | ----------------- | -------------------------------------------------------------------- |
| `quartz.scheduler.instanceName`    | `DefaultQuartzScheduler` | `QuartzScheduler` | Persistent stores key rows on the name                               |
| `quartz.jobStore.misfireThreshold` | 60 seconds               | 5 seconds         | Short delays now count as misfires and apply the misfire instruction |
| `quartz.serializer.type = json`    | Newtonsoft               | System.Text.Json  | Job data written by one may not read back the same in the other      |
| `PropagateTraceContext`            | Not present              | On                | Trace context flows into job execution                               |

The instance name deserves the most attention. An ADO.NET job store keys its rows on the scheduler name, so a 4.x node that never set `instanceName` looks for rows under `QuartzScheduler`, while all of your jobs and triggers are stored under `DefaultQuartzScheduler`. Set the name explicitly to the value the 3.x nodes used before the first 4.x node starts.

Later 4.x releases changed more behavior that a 3.x user will notice:

- **4.4:** a cancelled run is recorded as `Cancelled`, not as a success, and five consecutive fire failures put a trigger in the `ERROR` state; `MaxConsecutiveFireFailures = 0` restores the old behavior.
- **4.6:** `DefaultMisfireHandling` (default `SmartPolicy`) is set on the scheduler, and a schedule builder with no instruction stores none. A clustered node with no `InstanceId` now generates one instead of sharing `NON_CLUSTERED`.
- **4.7:** `QuartzSchedulerOptions.DefaultTimeZone` (default `TimeZoneInfo.Local`) applies when a trigger names no zone, and `InTimeZone(null)` now means "no zone" rather than local time. Job data serialization changed too: numeric, boolean, and null members of declared job-data objects read back as strings.

The 5-second misfire threshold interacts with your misfire instructions; [Quartz.NET misfire instructions](https://cronradar.com/blog/quartz-net-misfire-instructions) explains what each instruction does once a fire time counts as missed.

## What to Test Before Production

Run a 4.x build against a copy of the production job store, not an empty one. Most upgrade failures depend on stored data.

| Test                                                  | What it catches                                                 |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| Start a 4.x node against a migrated copy of the store | Missed schema scripts, stored expressions 4.x rejects           |
| Compare job and trigger counts before and after       | Instance name mismatch, unreadable job data                     |
| Read every `JobDataMap` key your jobs use             | `KeyNotFoundException`, values that now read as strings         |
| Fire each job once with `TriggerJob`                  | Job construction, DI registrations, serializer changes          |
| Stop the host during a run                            | Cancellation handling, `Cancelled` outcomes, shutdown listeners |
| Pause the scheduler for 10 seconds, then resume       | The 5-second misfire threshold and your instructions            |
| Check next fire times for zone-less triggers          | `DefaultTimeZone` and `InTimeZone(null)` changes                |
| Verify paused groups and triggers                     | Paused job groups that didn't carry over                        |

The last check that matters is time. A job that runs nightly or monthly won't fire during a deploy window, so it can be broken for days before anyone looks. That is what an external monitor is for.

## Keep Monitoring Working Through the Upgrade

`CronRadar.Quartz` 0.2.0 supports both majors and picks one by target framework: on .NET 10 it uses Quartz.NET 4, and on earlier frameworks it uses Quartz.NET 3.13 or later. If you upgrade the app to .NET 10 but stay on Quartz.NET 3 for a while, keep `CronRadar.Quartz` at 0.1.1 until Quartz moves too. On Quartz.NET 4 the call is the same:

```csharp
using CronRadar.Quartz;
using Quartz;

var scheduler = await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler();

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. Call after scheduling jobs.
await scheduler.MonitorAll();
await scheduler.Start();
```

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 registers a job listener that reports each run's start, completion, or failure, and translates each cron trigger to five-field cron so CronRadar knows when the next run is due.

What to check across the upgrade:

- **Monitor keys come from the `JobKey`** (or a `[CronRadar("key")]` attribute on the job class), so if job names and groups don't change, the same monitors keep receiving reports and keep their history. Don't rename jobs in the same release.
- **A job that stops firing after the upgrade is caught.** If the instance name, a rejected expression, or a misfire change stops a trigger, no start arrives. After 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. A job that throws reports a failure and alerts immediately.
- **Expressions with seconds stay unmonitored.** A cron trigger with no five-field form, such as one that fires on a seconds field other than 0, logs a warning and isn't monitored.
- **Time zones aren't converted.** CronRadar evaluates schedules in the application's time zone, set in its settings (UTC if unset). CronRadar.Quartz copies the trigger's hours as written, so a trigger in a different zone from the CronRadar application needs its own application in that zone. Check this if the 4.7 `DefaultTimeZone` change moved any zone-less trigger.

Use a separate CronRadar application and key for the environment where you test the upgrade, so a staging run can't report into production monitors.

## Frequently Asked Questions

### Does Quartz.NET 4 support .NET 8 or .NET Framework?

No. Quartz.NET 4.x requires .NET 10 or later, and every package targets `net10.0`. There is no `netstandard2.0` build and no support for `.config` files. Upgrade the application to .NET 10 first, or stay on Quartz.NET 3.x.

### Can Quartz.NET 3.x and 4.x nodes share one database during the upgrade?

Yes, for a rolling upgrade, as long as the 3.0-to-4.0 schema script ran first. The migration guide says the script is safe while 3.x nodes are still firing. Don't let a 4.0 node write a calendar while 3.x nodes are running, and run the optional index script only after the last 3.x node stops.

### Why are my jobs missing after upgrading to Quartz.NET 4?

The most likely cause with a database store is the scheduler instance name. Its default changed from `DefaultQuartzScheduler` to `QuartzScheduler`, and stored rows are keyed on the name, so a 4.x node that doesn't set `quartz.scheduler.instanceName` reads a different, empty scheduler. Set the name to the value your 3.x nodes used.

### What replaces StdSchedulerFactory in Quartz.NET 4?

`QuartzSchedulerBuilder`, for example `await QuartzSchedulerBuilder.Create(_ => { }).BuildScheduler()`, or the `AddQuartz()` dependency injection integration, which is now part of the main `Quartz` package. `SchedulerBuilder` and `DirectSchedulerFactory` were removed as well.

### Does CronRadar.Quartz work with Quartz.NET 4?

Yes, from 0.2.0. On .NET 10 the package uses Quartz.NET 4, and on earlier frameworks it uses Quartz.NET 3.13 or later. If you are on .NET 10 but still on Quartz.NET 3, keep `CronRadar.Quartz` at 0.1.1 until Quartz moves to 4.
