microsoft/aspire · error · FailedToApplyEnvironmentException

Failed to create executable launch plan for resource

Error message

Failed to create executable launch plan for resource '{renderedResource.ModelResource.Name}'. {ex.Message}

What it means

When building the executable launch plan fails with an unexpected (non-launch-configuration) exception, ExecutableCreator.CreateObjectAsync wraps it in FailedToApplyEnvironmentException, prefixing the original message. The comment notes this deliberately reports launch-planning failures with their specific cause without misclassifying them as IDE launch-configuration failures.

Solutions

Read the appended ex.Message in the exception and the resource logs to identify the specific cause
If a custom launch recipe is registered, debug/fix its CreateLaunchPlanAsync
Verify the resource's annotations are intact (exactly one launch recipe, valid launch policy)

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    await creator.CreateObjectAsync(renderedResource, resourceLogger, ct);
}
catch (FailedToApplyEnvironmentException ex) when (ex.Message.StartsWith("Failed to create executable launch plan"))
{
    // ex.InnerException + appended message identify the specific planning failure.
    logger.LogError(ex.InnerException, "Launch plan creation failed.");
}

Prevention

Ensure custom launch recipes handle all input states without throwing
Keep Aspire.Hosting and integration packages version-aligned
Log and validate annotations added by custom resource builders

When it happens

Trigger: Any exception other than the launch-configuration exception thrown during plan creation in ResolveLaunchPlanAsync — e.g., the launch policy decision logic throwing, or the recipe's CreateLaunchPlanAsync failing for a non-IDE reason.

Common situations: Custom ExecutableLaunchRecipeAnnotation recipes throwing; internal invariant failures during launch policy evaluation; bugs in resource-type integrations.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

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

        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);
    }

    internal static async Task<ExecutableLaunchPlan> ResolveLaunchPlanAsync(
        IResource resource,
        IExecutionConfigurationResult executionConfiguration,
        IConfiguration configuration,
        DistributedApplicationOptions distributedApplicationOptions,
        ExecutableLaunchPolicy launchPolicy,
        ILogger resourceLogger,
        CancellationToken cancellationToken)
    {

View on GitHub (pinned to 25830f84bd)