dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetGrainDirectoryOptions)} values for {na

Error message

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

What it means

Thrown by the ADO.NET grain directory options validator when the resolved AdoNetGrainDirectoryOptions instance is null. This is a dependency-injection failure: the options object could not be constructed/resolved by the DI container before validation ran. In practice it signals a misregistered or missing named options registration.

Source

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

using static System.String;

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

Register AdoNetGrainDirectoryOptions via Configure/ConfigureOptions for the same name used when adding the grain directory.
Use the AddAdoNetGrainDirectory extension helper which wires the options binding for you.
Verify the options name string matches between AddAdoNetGrainDirectory(name) and Configure<AdoNetGrainDirectoryOptions>(name).

Example fix

// before
builder.AddAdoNetGrainDirectory("MyDirectory");
// options never configured -> resolves null in some containers

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

Defensive patterns

Strategy: validation

Validate before calling

// Verify the named options resolve before validation runs.
var resolved = serviceProvider.GetService<IOptionsMonitor<AdoNetGrainDirectoryOptions>>()?.Get(name);
if (resolved is null) throw new InvalidOperationException($"AdoNetGrainDirectoryOptions '{name}' not registered.");

Prevention

Always pair AddAdoNetGrainDirectory(name) with a Configure delegate of the same name.
Prefer the configure-options overload of the registration extension.
Add an integration test that resolves each named options from the DI container.

When it happens

Trigger: ValidateConfiguration() is called on an AdoNetGrainDirectoryOptionsValidator whose `options` constructor parameter resolved to null. Happens when the grain directory was registered without a matching named AdoNetGrainDirectoryOptions binding, or when a custom DI container returns null for that service.

Common situations: Registering a named grain directory ("MyDirectory") without a corresponding Configure<AdoNetGrainDirectoryOptions>("MyDirectory", ...); using a custom IServiceProvider that returns default(null) for options; misordered DI registrations.

Related errors

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