dotnet/orleans · error · InvalidOperationException

Database provider factory: '{invariantName}' did not return

Error message

Database provider factory: '{invariantName}' did not return a connection object.

What it means

Thrown by DbConnectionFactory.CreateConnection when the resolved DbProviderFactory.CreateConnection() returns null. Under normal circumstances a registered provider factory always returns a connection instance; a null return indicates the connector assembly loaded but its factory is broken, misconfigured, or partially initialized.

Source

Thrown at src/AdoNet/Shared/Storage/DbConnectionFactory.cs:120

        public static DbConnection CreateConnection(string invariantName, string connectionString)
        {
            if (string.IsNullOrWhiteSpace(invariantName))
            {
                throw new ArgumentNullException(nameof(invariantName));
            }

            if (string.IsNullOrWhiteSpace(connectionString))
            {
                throw new ArgumentNullException(nameof(connectionString));
            }

            var factory = factoryCache.GetOrAdd(invariantName, GetFactory).Factory;
            var connection = factory.CreateConnection();

            if (connection == null)
            {
                throw new InvalidOperationException($"Database provider factory: '{invariantName}' did not return a connection object.");
            }

            connection.ConnectionString = connectionString;
            return connection;
        }

        public static void ValidateDataSource(string invariantName, DbDataSource dataSource)
        {
            ArgumentNullException.ThrowIfNull(dataSource);

            var factory = factoryCache.GetOrAdd(invariantName, GetFactory).Factory;
            using var expectedConnection = factory.CreateConnection()
                ?? throw new InvalidOperationException($"Database provider factory: '{invariantName}' did not return a connection object.");
            using var actualConnection = dataSource.CreateConnection();

            var expectedType = expectedConnection.GetType();
            var actualType = actualConnection.GetType();
            if (!expectedType.IsAssignableFrom(actualType))

View on GitHub (pinned to fca799fa70)

Solutions

Upgrade the ADO.NET connector package (e.g. Microsoft.Data.SqlClient, Npgsql, MySqlConnector) to a stable, supported version.
Verify the connector's native dependencies are present in the runtime environment.
If the problem persists, open an issue with the connector vendor, since CreateConnection should never return null.

Defensive patterns

Strategy: try-catch

Try / catch

try { var conn = DbConnectionFactory.CreateConnection(invariant, cs); }
catch (InvalidOperationException ex) when (ex.Message.Contains("did not return a connection"))
{
    // log and surface a connector-package/dependency problem
    throw new InvalidOperationException($"Connector '{invariant}' failed to produce a connection. Verify the package and native deps.", ex);
}

Prevention

Pin connector packages to stable, tested versions in your .csproj.
Include connector integration tests in CI that actually open a connection.
Verify native dependencies (e.g. SQLite native binaries) are present in the deployment image.

When it happens

Trigger: The invariant resolved successfully (so error 121 did not fire) and the assembly loaded, but factory.CreateConnection() yielded null. This is rare and points to a defective or unsupported version of the ADO.NET connector, or a factory singleton that has been corrupted.

Common situations: Using an outdated or preview version of a connector whose CreateConnection is known to return null; a connector that requires additional registration (e.g. SQLite native dependencies not present) leaving the factory in a degraded state; reflection retrieved a non-standard Instance field.

Related errors

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