// BLOG
Akka.Reminders: a Reliable, High-Speed, Durable, Distributed Scheduler for .NET
Replaces Quartz.NET integration inside Akka.NET.
For doing fast, high interval scheduling inside Akka.NET we’ve had the IWithTimers marker interface for years, but this tool is limited:
- Only runs so long as the actor is alive, so you can’t wake a stopped actor up when it’s time to do its work;
- Runs on intervals, not on a fixed schedule (i.e. “run every 20 seconds,” versus “run at midnight on Tuesdays”); and
- Is at-most-once with no acknowledgement or retry: if the actor crashes mid-tick, that occurrence is simply gone.
The best solution we’ve had for this type of durable, deadline-driven scheduling in the Akka.NET project was Akka.Quartz.Actor; naturally, this is built on top of Quartz.NET and tries to “actor-ize” some of that functionality to integrate with actors. But Akka.Quartz.Actor was never really designed to integrate with more modern features like Akka.Cluster.Sharding and just generally feels kind of janky compared to what it could be.
So in late 2025, I set out to create a brand new reliable, high-performance scheduler from the bottom-up designed for Akka.Cluster.Sharding-first, but an important caveat before some of you stop reading: it also works without Akka.Cluster.Sharding too and in fact this is what powers the reminders system inside Netclaw, which is used by thousands of Netclaw users globally on a daily basis.
Introducing: Akka.Reminders, a high performance durable, distributed scheduling solution built on top of Akka.NET and simple SQL tables.
Using Akka.Reminders
I originally created Akka.Reminders as a personal skunkworks project1 here: https://github.com/Aaronontheweb/akka-reminders, but as of Akka.NET v1.5.75 is it now an official module of the Akka.NET project.
We already have some Petabridge customers in banking and finance using Akka.Reminders to power things like clearing tens of thousands of market orders at market open in a matter of seconds, as they and other users have been working with us on making Akka.Reminders great over the course of 2026. Akka.Reminders is battle-tested and ready for production use.
When Should You Use Akka.Reminders?
You should use Akka.Reminders whenever any of the following conditions are true:
- You want stopped actors to be woken up and recreated by the reminders system when reminders are due;
- You want to schedule activities based around deadlines, i.e. midnight on Tuesdays; or
- You need stronger delivery guarantees that scheduled activity was actually completed within a given time allotment.
Akka.Reminders ticks all of these boxes, none of the other solutions do.
Supported Reminder Storage Backends
Akka.Reminders needs a place to store pending reminders and we opted for a customized, performance-optimized RDBMS index for this purpose rather than using Akka.Persistence, which is an append-only journal for event-sourcing purposes.
Here’s the set of supported storage back-ends for Akka.Reminders:
| Storage Backend | Package | Auto-Initialize | Documentation |
|---|---|---|---|
| In-Memory | Akka.Reminders |
N/A | Built-in (development/testing only) |
| SQL Server | Akka.Reminders.SqlServer |
Yes | SQL Server Schema |
| PostgreSQL | Akka.Reminders.PostgreSql |
Yes | PostgreSQL Schema |
| SQLite | Akka.Reminders.Sqlite |
Yes | SQLite Schema |
Netclaw, for instance, uses the Akka.Reminders.Sqlite implementation as a stand-alone process. But some of our other applications, such as TextForge and Sdkbin, use the Postgres and SQL Server implementations. All of them perform consistently well.
Benchmarks
Akka.Reminders is fast - these numbers are from the Akka.Reminders benchmarks running on a Ryzen 9 9900X, 24 logical CPUs, .NET 10 with Postgres in a Docker container:
| Scenario | Reminders | Median | Throughput |
|---|---|---|---|
| one-off | 25,000 | 1,038 ms | ~24,100/s |
| due-recurring | 25,000 | 1,110 ms | ~22,500/s |
| early-recurring | 25,000 | 1,374 ms | ~18,200/s |
| recurring-retry | 25,000 | 1,022 ms | ~24,500/s |
We can dispatch and mark as “delivered” approximately 22-25 thousand reminders per second with this hardware. That’s fast!
Configuring Akka.Reminders Storage
To use Akka.Reminders with one of the SQL back-ends, you just need to call this on the AkkaConfigurationBuilder (from Akka.Hosting:)
using Akka.Hosting;
using Akka.Reminders;
using Akka.Reminders.SqlServer.Hosting;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAkka("MySystem", (configBuilder, provider) =>
{
configBuilder
.WithClustering()
.WithShardRegion<MyEntity>(
"my-entities",
(system, registry, resolver) => entityId =>
Props.Create(() => new MyEntityActor(entityId)),
new MyMessageExtractor(),
new ShardOptions())
.WithReminders("reminder-host", reminders => reminders
.WithSqlServerStorage(
connectionString: builder.Configuration.GetConnectionString("Reminders"),
schemaName: "dbo",
tableName: "akka_reminders",
autoInitialize: true));
});
When autoInitialize is set to true, this will cause the SQL schema to be automatically populated using the schema and table names you provided.
[!NOTE] As a security best practice, we recommend applying the SQL Scripts (see the data table from earlier) for Akka.Reminders manually as part of a planned database migration first and leaving
autoInitialize: falsein production. You should also scope the SQL accounts that your application runs in production to not have DDL modification access (this is the case whether you use Akka.NET or not.)
This code will create an Akka.Cluster.Tools.Singleton responsible for owning the Akka.Reminders schedule and dispatching reminders to entity actors.
Scheduling Reminders
To actually schedule a reminder, we need to create an IReminderClient inside our entity actors:
public class MyEntityActor : ReceiveActor
{
private readonly IReminderClient _reminders;
public MyEntityActor(string entityId)
{
var extension = Context.System.ReminderClient();
_reminders = extension.CreateClient("my-entities", entityId);
ReceiveAsync<StartReminders>(async msg =>
{
// Schedule a one-time reminder that expires if it is more than 30 seconds late.
var result = await _reminders.ScheduleSingleReminderAsync(
new ReminderKey("my-reminder"),
DateTimeOffset.UtcNow.AddMinutes(5),
new DoSomething(),
maxDeliveryWindow: TimeSpan.FromSeconds(30));
if (result.ResponseCode == ReminderScheduleResponseCode.Success)
{
// Reminder scheduled successfully
}
});
ReceiveAsync<StartRecurringReminders>(async msg =>
{
// Schedule a recurring reminder that fires every hour
await _reminders.ScheduleRecurringReminderAsync(
new ReminderKey("hourly-check"),
DateTimeOffset.UtcNow.AddHours(1),
TimeSpan.FromHours(1),
new PerformHealthCheck());
});
ReceiveAsync<ReminderEnvelope<DoSomething>>(async envelope =>
{
if (envelope.Deadline.IsExpired())
{
await _reminders.AckAsync(envelope);
return;
}
// Handle the reminder when it fires
Console.WriteLine("Reminder received!");
// Acknowledge receipt so the scheduler marks it delivered.
// If AckAsync fails or times out, the reminder will be retried.
await _reminders.AckAsync(envelope);
});
}
}
The IReminderClient will locate the reminder scheduler singleton and will process all ScheduleSingleReminderAsync and ScheduleRecurringReminderAsync calls made against it, returning a ReminderScheduled response:
public sealed record ReminderScheduled(
ScheduleReminder OriginalCommand,
ReminderScheduleResponseCode ResponseCode,
string? Message = null) : IReminderResponse, IReminderWireMessage
{
/// <inheritdoc />
public ReminderEntity Entity => OriginalCommand.Entity;
/// <summary>
/// The key of the reminder that was scheduled.
/// </summary>
public ReminderKey Key => OriginalCommand.Key;
/// <summary>
/// When the reminder is scheduled to fire.
/// </summary>
public DateTimeOffset When => OriginalCommand.When;
}
If the reminder was successfully scheduled, the ReminderScheduleResponseCode will indicate it - otherwise, it’ll let you know if there was a reason this reminder could not be scheduled.
Consuming Reminders
Once the reminder is scheduled, it’ll fire at whatever point in time or interval you specified in the future - and it will be delivered via a ReminderEnvelope<TYourMessageType>:
ReceiveAsync<ReminderEnvelope<DoSomething>>(async envelope =>
{
if (envelope.Deadline.IsExpired())
{
await _reminders.AckAsync(envelope);
return;
}
// Handle the reminder when it fires
Console.WriteLine("Reminder received!");
// Acknowledge receipt so the scheduler marks it delivered.
// If AckAsync fails or times out, the reminder will be retried.
await _reminders.AckAsync(envelope);
});
In order to get Akka.Reminders to stop delivering reminders, we need to acknowledge that we have fully processed the reminder - we do so by taking the ReminderEnvelope and passing it into the IReminderClient.AckAsync function:
// Acknowledge receipt so the scheduler marks it delivered.
// If AckAsync fails or times out, the reminder will be retried.
await _reminders.AckAsync(envelope);
If that returns without error, we are in the clear.
Message Freshness and maxDeliveryWindow
The envelope.Deadline.IsExpired() shorthand here implements a TTL (time-to-live) value for this message, indicating if it has gone stale or not. Here is how that plays out:
- Reminder is due at
00:00:00with amaxDeliveryWindowof 15 seconds and; - Reminder fires for the first time at
00:00:00but is not acknowledged by your entity actor (i.e. network failure); - Reminder is re-delivered at
00:00:05,00:00:10, and finally00:00:15; - but your actor doesn’t process it until
00:00:17, which means per themaxDeliveryWindowdeadline you set this message is considered to be “expired” and should just automatically be ACKed without any re-processing.
This is useful in domains where the reminder is considered to be perishable - after a certain point in time, if the reminder arrives late enough it becomes pointless to process it. By default Akka.Reminders does not set this value for you. It’s optional!
The other scenario where
envelope.Deadline.IsExpired()could be set totrueis when you are using recurring reminders and an old instance of the reminder is about to be superseded by a newer instance.
I strongly encourage you to check envelope.Deadline.IsExpired() in all places where you are consuming reminders, as we recommended in our last post on “Improving Messaging Safety with Time-to-Live Values (TTLs) and Expiring Messages.”
Reminder Keys, Uniqueness, and Delivery Guarantees
The next thing worth discussing are how Akka.Reminders differentiates unique reminders and reminder destinations inside its schedule!
When we create an IReminderClient, the code looks like this:
var extension = Context.System.ReminderClient();
_reminders = extension.CreateClient("my-entities", entityId);
my-entities== the exact name of ourShardRegionfor this entity type;entityId== the extractedEntityIdfrom an Akka.Cluster.ShardingIMessageExtractor.
Akka.Reminders resolves ShardRegions by their entity names internally, and then uses the Akka.Cluster.Sharding routing system2 to deliver messages to your sharded entity actors so we can wake them up if they’re offline.
From there, each reminder is uniquely named with a key and a DateTimeOffset that specifies the unique “occurrence” of a reminder:
// Schedule a recurring reminder that fires every hour
await _reminders.ScheduleRecurringReminderAsync(
new ReminderKey("hourly-check"),
DateTimeOffset.UtcNow.AddHours(1),
TimeSpan.FromHours(1),
new PerformHealthCheck());
The ReminderKey identifies a unique timer instance, similar to how we accept regular objects for this purpose as part of Akka.NET’s built-in IWithTimers interface.
For a recurring reminder with many successive deliveries in the future, each occurrence is uniquely identified by its “due time” - when the reminder is due to be delivered to a recipient actor. Hence why when we acknowledge a delivered reminder, we just pass in the entire ReminderEnvelope<T> so we don’t have to sort that information out ourselves.
NACK-ing Reminders
The goal behind an acknowledgement protocol like the kind Akka.Reminders uses is to support “at least once” delivery, and the key to making that work is sending the acknowledgement back after the recipient has assumed responsibility for the processing.
So in scenarios where the recipient CANNOT accept responsibility for processing yet (i.e. database or some other dependency is offline), you can let the reminder scheduler know “I’m not able to process this right now” via:
// NACK so Akka.Reminders will apply the prescribed retry policy and re-deliver this to us in the future
await _reminders.NackAsync(envelope, reason:"Database is down right now.");
If you don’t NackAsync the message, you will get a re-delivery anyway but only after the default AckTimeout setting (applied at the time you configure Akka.Reminders inside Akka.Hosting) has elapsed.
Cancelling and Overwriting Reminders
Akka.Reminders absolutely supports both cancelling and overwriting reminders with new delivery schedules / payloads. Here’s how that works:
// Cancel just a single, specifically named reminder for this entity
await _reminders.CancelReminderAsync(new ReminderKey("hourly-check"));
// Cancel ALL reminders belonging to this entity
await _reminders.CancelAllRemindersAsync();
And for overwriting a reminder, we just call ScheduleSingleReminderAsync or ScheduleRecurringReminderAsync again:
// Schedule a recurring reminder that fires every hour
await _reminders.ScheduleRecurringReminderAsync(
new ReminderKey("hourly-check"),
DateTimeOffset.UtcNow.AddHours(3), // new initial delay
TimeSpan.FromHours(2), // new interval
new DifferentPayloadThisTimeCheck()); // new payload
All of the previously scheduled reminders for that key will be invalidated and will not be delivered. Only the new reminders in-flight going forward will be.
Default Delivery Guarantees
The Akka.Reminders documentation contains a detailed “failure modes” document that gets into the particulars, but I’ll try to summarize the delivery rules as simply as I can here:
- At least once delivery: reminders might be delivered more than once. The
(EntityId, ReminderKey, DateTimeOffset)key can be used to de-duplicate previously received reminders; - Akka.Reminders persists its state before delivery: this is designed to prevent duplicate delivery storms during database failures.
- Automatic retries: failed or unacknowledged deliveries are retried using exponential backoff, subject to retry limits and deadlines that you can specify.
- Latest-only recurring reminders: Missed occurrences are skipped rather than replayed. Older occurrences are superseded by newer ones.
- Safe handling of late acknowledgements: Stale acknowledgements cannot accidentally complete newer reminder occurrences.
The TL;DR; of this is, Akka.Reminders is built to take most of the hard decision-making and infrastructure issues out of your hands and give you something that is reliable, fast, and battle-tested already.
Even Stronger Delivery Guarantees
When we were introducing Akka.Reminders into Sdkbin to power parts of our billing cycle, one of the key elements we had to support was a “never give up on this reminder even after we’ve hit the maximum number of retry attempts” setting. This is baked into Akka.Reminders too:
var scheduled = await client.ScheduleSingleReminderAsync(
new ReminderKey("pending-work"),
dueAt,
new ProcessPendingWork(workId),
retryPolicy: ReminderRetryPolicy.UntilAcknowledged, // NEVER GIVE UP UNTIL WE ACK
ct: cancellationToken);
if (scheduled.ResponseCode != ReminderScheduleResponseCode.Success)
{
// Acceptance is unknown on timeout/storage error; retry scheduling according to application policy.
throw new InvalidOperationException(scheduled.Message);
}
This is really only necessary for mission-critical “one off” reminders. Recurring reminders do not need this setting.
Testing Reminders in the Akka.Hosting.TestKit
I try to avoid integration and end-to-end testing when I can because even though it’s useful it contributes to long execution times and slower development loops. So for my actors that use Akka.Reminders, we can test them using the Akka.Hosting.TestKit and in-memory reminder storage:
using Akka.Hosting;
using Akka.Reminders;
public class ReminderTests : Akka.Hosting.TestKit.TestKit
{
private readonly TestShardRegionResolver _resolver = new();
protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
{
// Configure local reminders - starts instantly without cluster
builder.WithLocalReminders(reminders => reminders
.WithInMemoryStorage()
.WithResolver(_resolver)
.WithSettings(new ReminderSettings
{
MaxSlippage = TimeSpan.FromMilliseconds(100),
MaxDeliveryAttempts = 3
}));
}
[Fact]
public async Task Reminder_ShouldDeliver_ToRegisteredShardRegion()
{
// Arrange
var targetActor = CreateTestProbe("billing-actor");
_resolver.RegisterShardRegion("billing-shard", targetActor);
var client = Sys.ReminderClient().CreateClient("billing-shard", "customer-123");
// Act - Schedule reminder
await client.ScheduleSingleReminderAsync(
new ReminderKey("retry-payment"),
DateTimeOffset.UtcNow.AddMilliseconds(200),
new PaymentRetry());
// Assert - Reminder delivered wrapped in ReminderEnvelope
var shardEnvelope = targetActor.ExpectMsg<ShardingEnvelope>(TimeSpan.FromSeconds(2));
Assert.Equal("customer-123", shardEnvelope.EntityId);
var reminderEnvelope = Assert.IsType<ReminderEnvelope<PaymentRetry>>(shardEnvelope.Message);
}
}
The key to making this all work is defining a custom IShardRegionResolver, which eliminates the need to run with Akka.Cluster or Akka.Cluster.Sharding enabled:
public sealed class TestShardRegionResolver : IShardRegionResolver
{
private readonly Dictionary<string, IActorRef> _shardRegions;
/// <summary>
/// Creates a new <see cref="TestShardRegionResolver"/> with no registered shard regions.
/// </summary>
public TestShardRegionResolver()
{
_shardRegions = new Dictionary<string, IActorRef>();
}
public void RegisterShardRegion(string regionName, IActorRef region)
{
_shardRegions[regionName] = region;
}
public bool UnregisterShardRegion(string regionName)
{
return _shardRegions.Remove(regionName);
}
/// <summary>
/// Gets the registered shard region names.
/// </summary>
public IEnumerable<string> RegisteredRegions => _shardRegions.Keys;
public IActorRef? TryResolve(ReminderEntity entity)
{
return _shardRegions.GetValueOrDefault(entity.ShardRegionName);
}
public void DeliverReminder(ReminderEntity entity, ReminderEnvelope envelope, IActorRef? sender = null)
{
var actor = TryResolve(entity);
actor?.Tell(envelope, sender ?? ActorRefs.NoSender);
}
}
Migration Notes from Aaron.Akka.Reminders
If you are upgrading from my original prototype Aaron.Akka.Reminders library, there’s a couple of migration steps to bear in mind:
- The package names are just
Akka.Remindersnow; rename any references toAaron.Akka.Reminders.*to justAkka.Reminders.*; the namespaces are still the same as they were before; - In 1.5.75 and in the next release of Akka.NET v1.6.0, there’s a new optional database migration you’ll want to run in order to support the
ReminderRetryPolicy.UntilAcknowledgedsetting. See the v1.5.75 upgrade guide here.
Try Akka.Reminders
Akka.Reminders is available now as part of Akka.NET v1.5.75, and it’s also included in the latest Akka.NET v1.6 beta. Here’s where to go next:
- Akka.Reminders docs and source code;
- Questions and feedback: the Akka.NET Discord or GitHub issues; and
- Video: I’ll be publishing a walkthrough of Akka.Reminders on the Petabridge YouTube channel.
Akka.Reminders is also the foundation for the next generation of higher-level Akka.NET libraries and frameworks, such as my latest prototype: Akka.Durable for durable entities, workflows, and eventually agents. So give Reminders a try and let us know how it works for you!
-
I also did this with our Akka.NET Aspire integration we shipped back in September. ↩
-
In the case of local reminders, the
IShardRegionResolverimplementation you configured with your Akka.Reminders config in Akka.Hosting can be used to substitute a localEntityTypeName–>IActorRefrouting scheme instead of relying on Akka.Cluster.Sharding. ↩
Observe and Monitor Your Akka.NET Applications with Phobos
Phobos automatically instruments your Akka.NET applications with OpenTelemetry — traces, metrics, and logs with built-in dashboards.
Enjoyed this post? Subscribe to our newsletter for more insights on distributed systems, Akka.NET, and .NET + AI.
// COMMENTS