dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetClusteringSiloOptions)} values for {na

Error message

Invalid {nameof(AdoNetClusteringSiloOptions)} values for {nameof(AdoNetClusteringTable)}. {nameof(options.Invariant)} is required.

What it means

Thrown by AdoNetClusteringSiloOptionsValidator.ValidateConfiguration when the configured Invariant on the silo-side clustering/reminders options is null or whitespace. Despite the validator class name (AdoNetClusteringSiloOptionsValidator), it is used for the reminder table options and asserts that options.Invariant is present, since the invariant identifies which ADO.NET provider to load for the reminder store. It fails fast at startup with an OrleansConfigurationException.

Source

Thrown at src/AdoNet/Orleans.Clustering.AdoNet/Options/AdoNetReminderTableOptionsValidator.cs:24

{
    /// <summary>
    /// Validates <see cref="AdoNetClusteringSiloOptions"/> configuration.
    /// </summary>
    public class AdoNetClusteringSiloOptionsValidator : IConfigurationValidator
    {
        private readonly AdoNetClusteringSiloOptions options;

        public AdoNetClusteringSiloOptionsValidator(IOptions<AdoNetClusteringSiloOptions> options)
        {
            this.options = options.Value;
        }

        /// <inheritdoc />
        public void ValidateConfiguration()
        {
            if (string.IsNullOrWhiteSpace(this.options.Invariant))
            {
                throw new OrleansConfigurationException($"Invalid {nameof(AdoNetClusteringSiloOptions)} values for {nameof(AdoNetClusteringTable)}. {nameof(options.Invariant)} is required.");
            }

            if (string.IsNullOrWhiteSpace(this.options.ConnectionString) == (this.options.DataSource is null))
            {
                throw new OrleansConfigurationException($"Invalid {nameof(AdoNetClusteringSiloOptions)} values for {nameof(AdoNetClusteringTable)}. Configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.");
            }
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Set Invariant to the correct ADO.NET provider invariant for your database (e.g. 'Microsoft.Data.SqlClient', 'Npgsql', 'MySql.Data.MySqlClient').
Ensure the corresponding DbProviderFactory is registered and the provider package is installed.
Verify the reminder options section is the one being read by the validator (named options).
Reuse the same invariant you use for clustering/persistence for consistency across stores.

Example fix

// before
builder.UseAdoNetReminderService(options =>
{
    options.ConnectionString = "Server=...;Database=OrleansReminders;...";
    // Invariant missing -> OrleansConfigurationException
});

// after
builder.UseAdoNetReminderService(options =>
{
    options.ConnectionString = "Server=...;Database=OrleansReminders;...";
    options.Invariant = "Microsoft.Data.SqlClient";
});

Defensive patterns

Strategy: validation

Validate before calling

// Validate reminder options at startup before the reminder service uses them
if (string.IsNullOrWhiteSpace(reminderOptions.Invariant))
    throw new OrleansConfigurationException("AdoNet reminder Invariant is required");
if (!DbProviderFactories.GetFactoryInvariantNames().Contains(reminderOptions.Invariant))
    throw new OrleansConfigurationException($"AdoNet provider invariant '{reminderOptions.Invariant}' is not registered");

Type guard

static bool HasValidInvariant(AdoNetClusteringSiloOptions o) =>
    !string.IsNullOrWhiteSpace(o.Invariant);

Try / catch

try { await silo.StartAsync(); }
catch (OrleansConfigurationException cx) when (cx.Message.Contains("Invariant is required"))
{
    _logger.LogCritical("Set the AdoNet reminder Invariant (e.g. 'Microsoft.Data.SqlClient')");
    throw;
}

Prevention

Always set Invariant in the AdoNet reminders config section.
Reuse the same ADO.NET invariant across clustering/persistence/reminders for consistency.
Register the DbProviderFactory and reference the provider package.
Validate the invariant against registered providers in a bootstrap check.

When it happens

Trigger: Produced at startup when AdoNetClusteringSiloOptions.Invariant is unset and the reminder options validator runs. Triggered by a missing/incomplete 'Invariant' in the AdoNet reminders configuration, a typo in the invariant string, or a config source returning empty.

Common situations: Appsettings section for reminders missing the Invariant field; partial config copied from clustering without the invariant; environment-specific config omitting the invariant; switching DB providers without updating the reminder provider.

Related errors

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