dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {na

Error message

Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {nameof(AdoNetGrainDirectory)}|{name}. Configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.

What it means

Thrown by the ADO.NET grain directory options validator when both ConnectionString and DataSource are set, or neither is. The grain directory requires exactly one connection source. The boolean equality check fires for both the all-unset and both-set cases.

Source

Thrown at src/AdoNet/Orleans.GrainDirectory.AdoNet/Options/AdoNetGrainDirectoryOptionsValidator.cs:25

/// </summary>
public class AdoNetGrainDirectoryOptionsValidator(AdoNetGrainDirectoryOptions options, string name) : IConfigurationValidator
{
    /// <inheritdoc />
    public void ValidateConfiguration()
    {
        if (options is null)
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {nameof(AdoNetGrainDirectory)}|{name}. {nameof(options)} is required.");
        }

        if (IsNullOrWhiteSpace(options.Invariant))
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {nameof(AdoNetGrainDirectory)}|{name}. {nameof(options.Invariant)} is required.");
        }

        if (IsNullOrWhiteSpace(options.ConnectionString) == (options.DataSource is null))
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {nameof(AdoNetGrainDirectory)}|{name}. Configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.");
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Provide exactly one of options.ConnectionString or options.DataSource.
Remove the redundant value if you migrated from one to the other.
Ensure the appsettings.json grain-directory section has a ConnectionString and no DataSource (or the reverse).

Example fix

// before
builder.AddAdoNetGrainDirectory("dir", o =>
{
    o.Invariant = AdoNetInvariants.InvariantNameSqlServer;
    o.ConnectionString = ""; // blank, DataSource null -> error
});

// after
builder.AddAdoNetGrainDirectory("dir", o =>
{
    o.Invariant = AdoNetInvariants.InvariantNameSqlServer;
    o.ConnectionString = "Server=.;Database=Orleans;Trusted_Connection=True;";
});

Defensive patterns

Strategy: validation

Validate before calling

static void CheckGrainDirectoryConnection(AdoNetGrainDirectoryOptions o)
{
    var exactlyOne = string.IsNullOrWhiteSpace(o.ConnectionString) != (o.DataSource is null);
    if (!exactlyOne)
        throw new InvalidOperationException("Set exactly one of ConnectionString or DataSource for the grain directory.");
}

Prevention

Use one connection strategy per subsystem and document it.
Add a startup assertion for exactly-one connection source.
During ConnectionString-to-DataSource migration, remove the old field atomically.

When it happens

Trigger: ValidateConfiguration() runs on AdoNetGrainDirectoryOptions where IsNullOrWhiteSpace(ConnectionString) equals (DataSource is null). Happens when only Invariant is configured, or when a DataSource and a ConnectionString are both provided.

Common situations: Configuring Invariant but forgetting the connection; supplying ConnectionString while also injecting a DbDataSource for pooling; migration mid-flight leaving both populated.

Related errors

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