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 when JournaledStateManagerOptions.JournalFormatKey is null, empty, or whitespace. A non-empty key is required to resolve the IJournalFormat keyed service; without one the provider cannot select a serialization format.

Source

Thrown at src/Azure/Orleans.Journaling.AzureStorage/AzureTableJournalStorageProvider.cs:146

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

    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.
Use the journaling Add* extension that configures both the key and the format registration together.
Bind the key from configuration and verify it is non-empty before startup.

Example fix

// before
services.Configure<JournaledStateManagerOptions>(o => { /* JournalFormatKey unset */ });
// after
services.Configure<JournaledStateManagerOptions>(o => o.JournalFormatKey = 'json');

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(journalFormatKey))
    throw new InvalidOperationException("JournalFormatKey must be non-empty.");

Type guard

static bool IsJournalFormatKeyValid(string? key) => !string.IsNullOrWhiteSpace(key);

Prevention

Set JournaledStateManagerOptions.JournalFormatKey explicitly in your Add* setup.
Bind the key from config and assert non-empty before startup.
Use the bundled extension methods which configure both key and registration.

When it happens

Trigger: JournaledStateManagerOptions.JournalFormatKey is left unset (null/empty) or explicitly cleared, and the AzureTableJournalStorageProvider constructor calls ValidateJournalFormatKey during DI activation.

Common situations: Default options not setting a JournalFormatKey; a config binding that supplies an empty string; an options post-configure step that nulls the key; misordered configuration.

Related errors

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