dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetClusteringClientOptions)} values for {

Error message

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

What it means

Thrown by AdoNetClusteringClientOptionsValidator.ValidateConfiguration when exactly one of ConnectionString or DataSource is not configured. The condition `IsNullOrWhiteSpace(ConnectionString) == (DataSource is null)` is true when both are set or both are unset, which the provider rejects because it needs exactly one source of database connectivity. ConnectionString is a full ADO.NET connection string; DataSource lets you supply a DbDataSource (e.g. NpgsqlDataSource) instead.

Source

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

    {
        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

Provide exactly one connectivity source: either ConnectionString (classic) or DataSource (DbDataSource), not both, not neither.
If migrating to DbDataSource, clear/omit ConnectionString from the options.
If using a plain connection string, leave DataSource unset and ensure ConnectionString is non-empty.
Validate the config section is not setting ConnectionString to an empty string (whitespace counts as unset).

Example fix

// before: both set
options.ConnectionString = "Server=...;...";
options.DataSource = npgsqlDataSource;

// after: keep exactly one
options.DataSource = npgsqlDataSource;
// (ConnectionString left null/unset)

Defensive patterns

Strategy: validation

Validate before calling

// Enforce exactly-one connectivity source before the silo uses clustering
bool hasCs = !string.IsNullOrWhiteSpace(options.ConnectionString);
bool hasDs = options.DataSource is not null;
if (hasCs == hasDs)
    throw new OrleansConfigurationException("Configure exactly one of ConnectionString or DataSource for AdoNet clustering");

Type guard

static bool HasExactlyOneConnectionSource(AdoNetClusteringClientOptions o) =>
    !string.IsNullOrWhiteSpace(o.ConnectionString) ^ (o.DataSource is not null);

Try / catch

try { await client.Connect(); }
catch (OrleansConfigurationException cx) when (cx.Message.Contains("Configure exactly one of"))
{
    _logger.LogCritical("Provide exactly one of ConnectionString or DataSource for AdoNet clustering");
    throw;
}

Prevention

When migrating to DbDataSource, clear the legacy ConnectionString.
Treat empty/whitespace ConnectionString as unset.
Validate the exactly-one invariant in a bootstrap check at startup.
Do not copy-paste config blocks without reconciling both fields.

When it happens

Trigger: Produced at startup when both ConnectionString and DataSource are provided, or when neither is provided. Triggered by setting both fields (ambiguous), by leaving both empty, or by a config edit that removed the connection string while a DataSource was never wired up.

Common situations: Migrating from ConnectionString to DbDataSource and accidentally leaving both populated; config template that sets ConnectionString to empty string while DataSource stays null; copy-paste between environments dropping the connection string; using DbDataSource injection without removing the legacy connection string.

Related errors

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