dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetClusteringClientOptions)} values for {

Error message

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

What it means

Thrown by AdoNetClusteringClientOptionsValidator.ValidateConfiguration when the configured Invariant (the AdoNet provider invariant name, e.g. 'System.Data.SqlClient' or 'Microsoft.Data.SqlClient') is null or whitespace. The invariant identifies which ADO.NET database provider to load, so a missing invariant makes the clustering table unusable; the validator fails fast at silo/client startup with an OrleansConfigurationException.

Source

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

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

        public AdoNetClusteringClientOptionsValidator(IOptions<AdoNetClusteringClientOptions> options)
        {
            this.options = options.Value;
        }

        /// <inheritdoc />
        public void ValidateConfiguration()
        {
            if (string.IsNullOrWhiteSpace(this.options.Invariant))
            {
                throw new OrleansConfigurationException($"Invalid {nameof(AdoNetClusteringClientOptions)} 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(AdoNetClusteringClientOptions)} 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' for SQL Server, 'Npgsql' for PostgreSQL, 'MySql.Data.MySqlClient' for MySQL).
Make sure the corresponding DbProviderFactory is registered (AdoNetInvariants.RegisterProvider / the provider package is referenced).
Validate the clustering config section is being read by the correct named options.
Confirm the DB provider package is installed so the invariant resolves at runtime.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

// Validate clustering client options at startup before the silo/client uses them
var inv = clusteringClientOptions.Invariant;
if (string.IsNullOrWhiteSpace(inv))
    throw new OrleansConfigurationException("AdoNet clustering Invariant is required");
if (!DbProviderFactories.GetFactoryInvariantNames().Contains(inv))
    throw new OrleansConfigurationException($"AdoNet provider invariant '{inv}' is not registered");

Type guard

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

Try / catch

try { await client.Connect(); }
catch (OrleansConfigurationException cx) when (cx.Message.Contains("Invariant is required"))
{
    _logger.LogCritical("Set AdoNetClusteringClientOptions.Invariant (e.g. 'Microsoft.Data.SqlClient')");
    throw;
}

Prevention

Always set Invariant in the AdoNet clustering config section.
Reference the DB provider package and register its DbProviderFactory.
Validate the invariant string against registered providers at startup.
Keep a config template that includes the invariant field.

When it happens

Trigger: Produced at startup when AdoNetClusteringClientOptions.Invariant is unset and the clustering client options validator runs. Triggered by a missing/incomplete 'Invariant' in the AdoNet clustering configuration section, a typo, or reading the value from a config source that returned empty.

Common situations: Appsettings section for clustering missing the Invariant field; copied a partial config block; environment-specific config that omits the invariant; switching DB providers but forgetting to update the invariant string.

Related errors

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