// 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:

  1. 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;
  2. Runs on intervals, not on a fixed schedule (i.e. “run every 20 seconds,” versus “run at midnight on Tuesdays”); and
  3. 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:

  1. You want stopped actors to be woken up and recreated by the reminders system when reminders are due;
  2. You want to schedule activities based around deadlines, i.e. midnight on Tuesdays; or
  3. 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: false in 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:

  1. Reminder is due at 00:00:00 with a maxDeliveryWindow of 15 seconds and;
  2. Reminder fires for the first time at 00:00:00 but is not acknowledged by your entity actor (i.e. network failure);
  3. Reminder is re-delivered at 00:00:05, 00:00:10, and finally 00:00:15;
  4. but your actor doesn’t process it until 00:00:17, which means per the maxDeliveryWindow deadline 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 to true is 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 our ShardRegion for this entity type;
  • entityId == the extracted EntityId from an Akka.Cluster.Sharding IMessageExtractor.

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:

  1. The package names are just Akka.Reminders now; rename any references to Aaron.Akka.Reminders.* to just Akka.Reminders.*; the namespaces are still the same as they were before;
  2. 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.UntilAcknowledged setting. 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 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!

  1. I also did this with our Akka.NET Aspire integration we shipped back in September. ↩

  2. In the case of local reminders, the IShardRegionResolver implementation you configured with your Akka.Reminders config in Akka.Hosting can be used to substitute a local EntityTypeName –> IActorRef routing 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.

Aaron Stannard

Aaron Stannard

CEO & Co-Founder, Petabridge

Creator of Akka.NET. Building distributed systems infrastructure for .NET since 2015. Writes about OSS business models, distributed architecture, and the intersection of AI and systems programming.

x.com/Aaronontheweb →

Enjoyed this post? Subscribe to our newsletter for more insights on distributed systems, Akka.NET, and .NET + AI.

Read more about: Akka.NET Business Case Studies Engineering NBench Product Videos
ref: comments

// COMMENTS

ref: newsletter

// STAY_CONNECTED