microsoft/aspire · error · InvalidOperationException

. needs to be set when a custom Execution Strategy is…

Error message

{nameof(MicrosoftEntityFrameworkCoreSqlServerSettings)}.{nameof(MicrosoftEntityFrameworkCoreSqlServerSettings.DisableRetry)} needs to be set when a custom Execution Strategy is configured.

What it means

Aspire detects a custom (non-default) SQL Server ExecutionStrategy configured on the DbContext options. Because Aspire manages retry behavior via DisableRetry/EnableRetryOnFailure, a custom strategy would be clobbered or conflict; the developer must opt out by setting DisableRetry = true so Aspire leaves the custom strategy alone.

Solutions

Set DisableRetry = true in MicrosoftEntityFrameworkCoreSqlServerSettings (config section or settings callback) to keep the custom strategy.
Or remove the custom ExecutionStrategy registration and let Aspire enable the built-in SqlServerExecutionStrategy retry-on-failure.
If the custom strategy subclasses SqlServerExecutionStrategy intentionally, subclass or align so the exact type matches, or disable Aspire retry.

Example fix

// before
builder.AddSqlServerDbContext<OrderContext>("sqldb", null, o => o.ExecutionStrategy(ctx => new MyCustomStrategy(ctx)));
// after
builder.AddSqlServerDbContext<OrderContext>("sqldb", s => s.DisableRetry = true, o => o.ExecutionStrategy(ctx => new MyCustomStrategy(ctx)));

Defensive patterns

Strategy: validation

Validate before calling

// if you register a custom ExecutionStrategy, also assert DisableRetry
if (registersCustomExecutionStrategy &&
    builder.Configuration["Aspire:Microsoft:EntityFrameworkCore:SqlServer:DisableRetry"] != "true")
{
    throw new InvalidOperationException("Set DisableRetry=true when using a custom ExecutionStrategy.");
}

Type guard

bool CustomStrategyAllowed(bool hasCustomStrategy, bool disableRetry) => !hasCustomStrategy || disableRetry;

Try / catch

try { builder.AddSqlServerDbContext<OrderContext>("sqldb", settingsCallback, optionsCallback); }
catch (InvalidOperationException ex) when (ex.Message.Contains("DisableRetry")) { // set DisableRetry=true in settingsCallback or drop the custom strategy }

Prevention

Pair every custom ExecutionStrategy registration with DisableRetry=true.
Prefer Aspire's built-in retry (EnableRetryOnFailure) over custom strategies when migrating.
Document custom retry behavior near the DbContext registration.

When it happens

Trigger: Registering a custom ExecutionStrategy (any class derived from SqlServerExecutionStrategy or replacing it via ExecutionStrategy extension) in configureDbContextOptions while MicrosoftEntityFrameworkCoreSqlServerSettings.DisableRetry is not set to true.

Common situations: Apps that implemented custom transient-fault handling before adopting Aspire; retry policy wrappers added via EF Core interceptors/strategies; copy-pasting pre-Aspire OnConfiguring code into the Aspire configureDbContextOptions callback.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/8f9278107bb6d12b. Report an issue: GitHub.

Appendix: source

Thrown at src/Components/Aspire.Microsoft.EntityFrameworkCore.SqlServer/AspireSqlServerEFCoreSqlClientExtensions.cs:146

                    var extension = optionsBuilder.Options.FindExtension<SqlServerOptionsExtension>();

                    if (!settings.DisableRetry)
                    {
                        var executionStrategy = extension?.ExecutionStrategyFactory?.Invoke(new ExecutionStrategyDependencies(null!, optionsBuilder.Options, null!));

                        if (executionStrategy != null)
                        {
                            if (executionStrategy is SqlServerRetryingExecutionStrategy)
                            {
                                // Keep custom Retry strategy.
                                // Any sub-class of SqlServerRetryingExecutionStrategy is a valid retry strategy
                                // which shouldn't be replaced even with DisableRetry == false
                            }
                            else if (executionStrategy.GetType() != typeof(SqlServerExecutionStrategy))
                            {
                                // Check SqlServerExecutionStrategy specifically (no 'is'), any sub-class is treated as a custom strategy.

                                throw new InvalidOperationException($"{nameof(MicrosoftEntityFrameworkCoreSqlServerSettings)}.{nameof(MicrosoftEntityFrameworkCoreSqlServerSettings.DisableRetry)} needs to be set when a custom Execution Strategy is configured.");
                            }
                            else
                            {
                                options.EnableRetryOnFailure();
                            }
                        }
                        else
                        {
                            options.EnableRetryOnFailure();
                        }
                    }

                    if (settings.CommandTimeout.HasValue)
                    {
                        if (extension != null &&
                            extension.CommandTimeout.HasValue &&
                            extension.CommandTimeout != settings.CommandTimeout)
                        {

View on GitHub (pinned to 25830f84bd)