dotnet/orleans · error · ArgumentException

The name of invariant must contain characters

Error message

The name of invariant must contain characters

What it means

Thrown by RelationalStorage.CreateInstance(string invariantName, string connectionString) when invariantName is null, empty, or whitespace. The invariant name (e.g. 'System.Data.SqlClient') selects the ADO.NET provider via DbProviderFactories, so a blank value cannot resolve a factory. This is a startup/configuration ArgumentException with the offending parameter named.

Source

Thrown at src/AdoNet/Shared/Storage/RelationalStorage.cs:98

        {
            get
            {
                return _connectionString;
            }
        }


        /// <summary>
        /// Creates an instance of a database of type <see cref="IRelationalStorage"/>.
        /// </summary>
        /// <param name="invariantName">The invariant name of the connector for this database.</param>
        /// <param name="connectionString">The connection string this database should use for database operations.</param>
        /// <returns></returns>
        public static IRelationalStorage CreateInstance(string invariantName, string connectionString)
        {
            if (string.IsNullOrWhiteSpace(invariantName))
            {
                throw new ArgumentException("The name of invariant must contain characters", nameof(invariantName));
            }

            if (string.IsNullOrWhiteSpace(connectionString))
            {
                throw new ArgumentException("Connection string must contain characters", nameof(connectionString));
            }

            return new RelationalStorage(invariantName, connectionString);
        }

        /// <summary>
        /// Creates an instance of a database of type <see cref="IRelationalStorage"/>.
        /// </summary>
        /// <param name="invariantName">The invariant name of the connector for this database.</param>
        /// <param name="dataSource">The data source used to open database connections.</param>
        /// <returns>A relational storage instance.</returns>
        public static IRelationalStorage CreateInstance(string invariantName, DbDataSource dataSource)
        {

View on GitHub (pinned to fca799fa70)

Solutions

1. Set the invariant name in your silo/client configuration, e.g. AdoNetInvariantName = "System.Data.SqlClient" or the MySql/Oracle/Npgsql invariant.
2. Verify the string is non-empty after config binding; log it at startup before calling CreateInstance.
3. Use the 3-argument CreateInstance overload only if you intend to pass a DbDataSource; otherwise ensure invariantName is set.
4. Confirm the chosen invariant is registered with DbProviderFactories in your runtime.

Example fix

// before
var storage = RelationalStorage.CreateInstance("", connectionString);

// after
var storage = RelationalStorage.CreateInstance("System.Data.SqlClient", connectionString);

if (string.IsNullOrWhiteSpace(invariantName))
    throw new InvalidOperationException("ADO.NET invariant name is not configured.");

static bool IsValidInvariant(string? s) => !string.IsNullOrWhiteSpace(s);

try { storage = RelationalStorage.CreateInstance(invariant, cs); }
catch (ArgumentException ex) when (ex.ParamName == nameof(invariant)) { /* fix config */ }

When it happens

Trigger: Calling IRelationalStorage storage = RelationalStorage.CreateInstance(invariantName, connectionString) with a missing/blank invariant. Common when the invariant is read from a config section, environment variable, or options object that was not bound.

Common situations: Misconfigured Orleans AdoNet provider options (AdoNetInvariantName left empty); wrong casing/typo in the invariant string; options binding skipped so the property defaults to null; CI deploy using a different config file than local.

Related errors

• Connection string must contain characters
• Configure exactly one of {nameof(connectionString)} or {name
• Invalid offset length
• Value cannot be null. (Parameter 'query')
• Value cannot be null. (Parameter 'selector')

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