dotnet/orleans · critical · InvalidOperationException

Journal format key '{journalFormatKey}' requires keyed servi

Error message

Journal format key '{journalFormatKey}' requires keyed service '{typeof(IJournalFormat).FullName}', but none was registered.

What it means

Thrown by AzureBlobJournalStorageProvider during construction when the configured journal format key resolves to no registered keyed IJournalFormat service. The provider looks up the format by key (from JournaledStateManagerOptions.JournalFormatKey) via GetKeyedService; a missing registration means no format plugin can serialize/deserialize journal data, so startup fails.

Source

Thrown at src/Azure/Orleans.Journaling.AzureStorage/AzureBlobJournalStorageProvider.cs:126

    {
        try
        {
            journalId = new JournalId(value);
            return true;
        }
        catch (ArgumentException)
        {
            journalId = default;
            return false;
        }
    }

    private static IJournalFormat GetJournalFormat(IServiceProvider serviceProvider, string journalFormatKey)
    {
        var journalFormat = serviceProvider.GetKeyedService<IJournalFormat>(journalFormatKey);
        if (journalFormat is null)
        {
            throw new InvalidOperationException(
                $"Journal format key '{journalFormatKey}' requires keyed service '{typeof(IJournalFormat).FullName}', but none was registered.");
        }

        if (!string.Equals(journalFormat.FormatKey, journalFormatKey, StringComparison.Ordinal))
        {
            throw new InvalidOperationException(
                $"Journal format key '{journalFormatKey}' resolved format '{journalFormat.GetType().FullName}', but its {nameof(IJournalFormat.FormatKey)} is '{journalFormat.FormatKey}'. " +
                "Register the journal format using the same key it reports.");
        }

        return journalFormat;
    }

    private static string ValidateJournalFormatKey(string? journalFormatKey)
    {
        if (string.IsNullOrWhiteSpace(journalFormatKey))
        {
            throw new InvalidOperationException("The configured journal format key must be non-empty.");

View on GitHub (pinned to fca799fa70)

Solutions

Register the IJournalFormat implementation under the exact key specified by JournaledStateManagerOptions.JournalFormatKey, e.g. services.AddKeyedSingleton<IJournalFormat>("json", (sp, _) => new JsonJournalFormat()).
Ensure the format key in configuration matches the key used at registration (case-sensitive, ordinal).
Check that the package providing your IJournalFormat implementation is referenced.

Example fix

// before
managerOptions.JournalFormatKey = "json";
// missing: no IJournalFormat registration for "json"

// after
managerOptions.JournalFormatKey = "json";
services.AddKeyedSingleton<IJournalFormat>("json", (sp, _) => new JsonJournalFormat());

Defensive patterns

Strategy: validation

Validate before calling

// Validate at startup that the keyed service exists:
using var scope = services.BuildServiceProvider().CreateScope();
var fmt = scope.ServiceProvider.GetKeyedService<IJournalFormat>(managerOptions.JournalFormatKey);
if (fmt is null) throw new InvalidOperationException($"No IJournalFormat registered for '{managerOptions.JournalFormatKey}'.");

Prevention

Register IJournalFormat keyed services in the same composition root that sets JournalFormatKey.
Add a startup health check that resolves the keyed service.
Pin the format key in a shared constant to avoid drift between config and registration.

When it happens

Trigger: Setting JournaledStateManagerOptions.JournalFormatKey to a value (e.g. 'json') but forgetting to register the corresponding keyed IJournalFormat service with services.AddKeyedSingleton<IJournalFormat>("json", ...). The provider constructor runs during DI activation.

Common situations: Upgrading to a version that renamed the default format key; adding a custom format without registering it; mispelling the format key between configuration and registration; removing a format package from project references.

Related errors

AI-assisted analysis of dotnet/orleans@fca799fa70 (2026-08-13). Data as JSON: /api/errors/ba001010dfb22198. Report an issue: GitHub.