dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetClusteringSiloOptions)} values for {na

Error message

Invalid {nameof(AdoNetClusteringSiloOptions)} values for {nameof(AdoNetClusteringTable)}. Configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.

What it means

Thrown by the ADO.NET clustering configuration validator when both ConnectionString and DataSource are set, or when neither is set. AdoNetClusteringTable needs exactly one connection source to open a database connection. The check `IsNullOrWhiteSpace(ConnectionString) == (DataSource is null)` is true (and throws) in both the all-empty and both-set cases.

Source

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

    {
        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 exactly one of options.ConnectionString or options.DataSource in the clustering configuration.
If migrating to DbDataSource, remove the now-redundant ConnectionString value.
If using appsettings.json, ensure the clustering config section contains a non-blank ConnectionString and no DataSource (or vice-versa).

Example fix

// before
builder.UseAdoNetClustering(options =>
{
    options.Invariant = AdoNetInvariants.InvariantNameSqlServer;
    // both unset -> error
});

// after
builder.UseAdoNetClustering(options =>
{
    options.Invariant = AdoNetInvariants.InvariantNameSqlServer;
    options.ConnectionString = "Server=.;Database=Orleans;Trusted_Connection=True;";
});

Defensive patterns

Strategy: validation

Validate before calling

// Run before host start to fail fast with a clearer message.
static void CheckClustering(AdoNetClusteringSiloOptions o)
{
    var exactlyOne = string.IsNullOrWhiteSpace(o.ConnectionString) != (o.DataSource is null);
    if (!exactlyOne)
        throw new InvalidOperationException("Set exactly one of ConnectionString or DataSource for clustering.");
}

Prevention

Centralize all ADO.NET connection setup in one Configure delegate per subsystem.
Add a startup health check that asserts exactly one connection source before Build().
When migrating ConnectionString -> DataSource, delete the old value in the same commit.

When it happens

Trigger: Calling ValidateConfiguration() (run by the silo host at startup) on AdoNetClusteringSiloOptions when ConnectionString is blank AND DataSource is null, or when a ConnectionString is supplied AND a DbDataSource is also supplied. Triggered via AddAdoNetClustering / UseAdoNetClustering registration paths.

Common situations: Forgetting the connection string in appsettings.json under the clustering section; supplying only an Invariant with no connection info; or migrating from ConnectionString to DbDataSource and leaving the old ConnectionString populated so both resolve.

Related errors

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