dotnet/orleans · critical · InvalidOperationException

Connection string '{connectionName}' was not found.

Error message

Connection string '{connectionName}' was not found.

What it means

Thrown by the CosmosGrainStorageProviderBuilder when configuration specifies a ConnectionName (to look up via IConfiguration.GetConnectionString) but no matching connection string is registered in the application configuration. The code checks: if ConnectionName is non-empty and ConnectionString is empty, it looks up IConfiguration.GetConnectionString(connectionName); if that also returns null/empty, it throws InvalidOperationException.

Source

Thrown at src/Azure/Orleans.Persistence.Cosmos/CosmosGrainStorageProviderBuilder.cs:45

            optionsBuilder.Bind(configurationSection);
            optionsBuilder.Configure<IServiceProvider>((options, services) =>
            {
                var serviceKey = configurationSection["ServiceKey"];
                if (!string.IsNullOrEmpty(serviceKey))
                {
                    options.ConfigureCosmosClient(
                        provider => new ValueTask<CosmosClient>(provider.GetRequiredKeyedService<CosmosClient>(serviceKey)));
                    return;
                }

                var connectionName = configurationSection["ConnectionName"];
                var connectionString = configurationSection["ConnectionString"];
                if (!string.IsNullOrEmpty(connectionName) && string.IsNullOrEmpty(connectionString))
                {
                    connectionString = services.GetRequiredService<IConfiguration>().GetConnectionString(connectionName);
                    if (string.IsNullOrEmpty(connectionString))
                    {
                        throw new InvalidOperationException($"Connection string '{connectionName}' was not found.");
                    }
                }

                if (!string.IsNullOrEmpty(connectionString))
                {
                    options.ConfigureCosmosClient(connectionString);
                }
            });
        });
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

1. Add a ConnectionStrings section to appsettings.json with the matching key, e.g., "ConnectionStrings": { "MyCosmos": "AccountEndpoint=..." }.
2. Verify the ConnectionName in the Orleans configuration section matches the key under ConnectionStrings exactly.
3. Alternatively, set the ConnectionString property directly in the Orleans config section instead of using ConnectionName.
4. Use environment variables or user secrets to provide the connection string in the deployment environment.

Example fix

// before: appsettings.json missing connection string
{
  "Orleans": { "Persistence": { "Cosmos": { "ConnectionName": "AzureCosmos" } } }
}

// after: add the matching connection string
{
  "ConnectionStrings": {
    "AzureCosmos": "AccountEndpoint=https://...;AccountKey=..."
  },
  "Orleans": { "Persistence": { "Cosmos": { "ConnectionName": "AzureCosmos" } } }
}

// At startup, verify the connection string resolves
var connectionName = configuration["Orleans:Persistence:Cosmos:ConnectionName"];
if (!string.IsNullOrEmpty(connectionName))
{
    var cs = configuration.GetConnectionString(connectionName);
    if (string.IsNullOrEmpty(cs))
        throw new InvalidOperationException($"Connection string '{connectionName}' not found in IConfiguration.");
}

try { await host.StartAsync(ct); }
catch (InvalidOperationException ex) when (ex.Message.Contains("was not found"))
{
    logger.LogCritical(ex, "Cosmos connection string missing — check ConnectionStrings section in config.");
    throw;
}

When it happens

Trigger: In the provider builder's PostConfigure step, the configuration section has a ConnectionName key but the IConfiguration system has no connection string registered under that name. Alternatively, both ConnectionName and ConnectionString are empty/unset but the code path still tries the lookup.

Common situations: appsettings.json is missing the ConnectionStrings:AzureCosmosDB section. The ConnectionName value in the Orleans config section doesn't match the key under ConnectionStrings. Environment variable for the connection string not set in the deployment. Typo in the connection name. CI/test environment without the connection string configured.

Related errors

• Orleans:AdvertisedIPAddress must contain the Container Apps
• {key} must be a valid TCP port.
• Value cannot be null. (Parameter 'connectionString')
• Connection string must contain characters
• No credentials specified. Use the {options.GetType().Name}.C

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