What causes "The configured journal format key must be non-empty." in dotnet/orleans?

Set JournaledStateManagerOptions.JournalFormatKey to a non-empty key that matches a registered IJournalFormat.

dotnet/orleans · critical · InvalidOperationException

The configured journal format key must be non-empty.

Error message

The configured journal format key must be non-empty.

What it means

Thrown by ValidateJournalFormatKey during provider construction when JournaledStateManagerOptions.JournalFormatKey is null, empty, or whitespace. The format key is required to resolve the IJournalFormat service; an empty key cannot be looked up and is rejected before any DI resolution.

Source

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

            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.");
        }

        return journalFormatKey;
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Set JournaledStateManagerOptions.JournalFormatKey to a non-empty key that matches a registered IJournalFormat.
Bind the options from configuration and verify the key is present (e.g. appsettings.json 'Journaling:JournalFormatKey': 'json').
Add an IValidateOptions<JournaledStateManagerOptions> that rejects empty format keys at startup.

Example fix

// before
// JournaledStateManagerOptions.JournalFormatKey never set → null

// after
services.Configure<JournaledStateManagerOptions>(o => o.JournalFormatKey = "json");

Defensive patterns

Strategy: validation

Validate before calling

services.AddOptions<JournaledStateManagerOptions>()
    .Validate(o => !string.IsNullOrWhiteSpace(o.JournalFormatKey), "JournalFormatKey must be non-empty.")
    .ValidateOnStart();

Prevention

Always set JournalFormatKey in configuration (e.g. appsettings 'Journaling:JournalFormatKey').
Add ValidateOnStart so an empty key fails the host startup with a clear message.
Pin the key in a constant shared between config and registration.

When it happens

Trigger: Constructing AzureBlobJournalStorageProvider when JournaledStateManagerOptions.JournalFormatKey is unset (null) or whitespace. The check runs at the top of the provider constructor.

Common situations: Not configuring JournaledStateManagerOptions at all; clearing the JournalFormatKey during a refactor; reading configuration from a missing section that yields null.

Related errors

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