dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {na

Error message

Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {nameof(AdoNetGrainDirectory)}|{name}. {nameof(options.Invariant)} is required.

What it means

Thrown by the ADO.NET grain directory options validator when the Invariant property is null or whitespace. The invariant (e.g. "System.Data.SqlClient") tells Orleans which ADO.NET driver and query dialect to use, and is mandatory because the grain directory has no default unlike grain storage.

Source

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

namespace Orleans.Configuration;

/// <summary>
/// Validates <see cref="AdoNetGrainDirectoryOptions"/> configuration.
/// </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

Set options.Invariant explicitly, e.g. AdoNetInvariants.InvariantNameSqlServer.
Use the AddAdoNetGrainDirectory overload that accepts a configure delegate and set Invariant there.
Double-check the configured section in appsettings.json includes an "Invariant" key.

Example fix

// before
builder.AddAdoNetGrainDirectory("dir", o =>
{
    o.ConnectionString = "Server=.;Database=Orleans;";
});

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

Defensive patterns

Strategy: validation

Validate before calling

static void CheckGrainDirectory(AdoNetGrainDirectoryOptions o)
{
    if (string.IsNullOrWhiteSpace(o.Invariant))
        throw new InvalidOperationException("AdoNetGrainDirectoryOptions.Invariant is required.");
}

Prevention

Do not assume Invariant defaults for the grain directory — set it explicitly.
Keep an invariant constant (e.g. AdoNetInvariants.InvariantNameSqlServer) referenced everywhere.
Validate the appsettings section contains an Invariant key in a config test.

When it happens

Trigger: ValidateConfiguration() runs on AdoNetGrainDirectoryOptions whose Invariant was never set. AdoNetGrainDirectoryOptions.Invariant has no default (unlike storage which defaults to SQL Server), so any registration that omits the invariant triggers this.

Common situations: Adding a grain directory with only a connection string and forgetting the Invariant; assuming Invariant defaults to SQL Server (it does not for the grain directory); copy-paste from storage config where Invariant has a default.

Related errors

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