microsoft/aspire · error · FailedToApplyEnvironmentException

Failed to apply launch configuration for resource

Error message

Failed to apply launch configuration for resource '{renderedResource.ModelResource.Name}'. Aspire does not retry launch configuration failures using DCP process fallback.

What it means

When building the executable launch plan fails with the designated launch-configuration exception type, ExecutableCreator.CreateObjectAsync logs the failure and rethrows it as FailedToApplyEnvironmentException with an explicit note that Aspire does not retry launch configuration failures via the DCP process fallback. This distinguishes deterministic launch configuration errors from transient ones so users know retrying will not help.

Solutions

Read the resource logs (resourceLogger.LogError) for the underlying exception captured as ex and fix it
For project resources, fix or regenerate launchSettings.json / launch profiles
If the launch recipe is custom, fix its CreateLaunchPlanAsync implementation; no DCP fallback retry will occur

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    await creator.CreateObjectAsync(renderedResource, resourceLogger, ct);
}
catch (FailedToApplyEnvironmentException ex) when (ex.Message.Contains("does not retry"))
{
    // Deterministic launch-config failure — fix launchSettings/profiles; retries will not help.
}

Prevention

Keep launchSettings.json valid and regenerate it after SDK/IDE upgrades
Test project launch profiles outside the AppHost first
Do not rely on DCP fallback retries for launch configuration failures

When it happens

Trigger: recipes[0].Recipe.CreateLaunchPlanAsync (via ResolveLaunchPlanAsync) throwing the specific launch-configuration exception type caught by the handler — e.g., IDE launch configuration production failing for a project resource.

Common situations: A launchSettings.json/profile problem for project resources; an IDE launch profile that cannot be translated; misconfigured launch settings after SDK or IDE changes.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/ExecutableCreator.cs:97

        }
        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
        {
            throw;
        }
        catch (FailedToApplyEnvironmentException ex)
        {
            resourceLogger.LogError(ex, "{Message}", ex.Message);
            throw;
        }
        catch (ExecutableLaunchConfigurationException ex)
        {
            var failureMessage =
                $"Failed to apply launch configuration for resource '{renderedResource.ModelResource.Name}'. " +
                "Aspire does not retry launch configuration failures using DCP process fallback.";
            // DcpExecutor avoids duplicating FailedToApplyEnvironmentException logs, so record the underlying
            // launch producer failure on the resource logger before surfacing the actionable error.
            resourceLogger.LogError(ex, "{Message}", failureMessage);
            throw new FailedToApplyEnvironmentException(failureMessage, ex);
        }
        catch (Exception ex)
        {
            var failureMessage =
                $"Failed to create executable launch plan for resource '{renderedResource.ModelResource.Name}'. " +
                ex.Message;
            // Report launch-planning failures with their specific cause without misclassifying recipe or invariant
            // errors as IDE launch-configuration failures.
            resourceLogger.LogError(ex, "{Message}", failureMessage);
            throw new FailedToApplyEnvironmentException(failureMessage, ex);
        }

        Render(renderedResource, plan, configuration.PemCertificates, _logger);

        await factory
            .CreateDcpObjectsAsync([renderedResource.DcpResource], cancellationToken)
            .ConfigureAwait(false);
    }

View on GitHub (pinned to 25830f84bd)