microsoft/aspire · error · FailedToApplyEnvironmentException

Resource ' ' declares " " debug launch support…

Error message

Resource '{context.Resource.Name}' declares "{debugSupport.LaunchConfigurationType}" debug launch support (WithDebugSupport) but has no project metadata. The "{debugSupport.LaunchConfigurationType}" launch configuration type is reserved for .NET project resources; use a resource that carries IProjectMetadata or a different launch configuration type.

What it means

WithDebugSupport with a project launch configuration type is only valid for resources carrying IProjectMetadata (i.e., .NET project resources). During CreateLaunchConfigurationsAsync, if a non-project resource declares a project launch configuration type, a FailedToApplyEnvironmentException is thrown with guidance to fix the declaration.

Solutions

  1. Only call WithDebugSupport with a project launch configuration type on ProjectResource instances (AddProject results)
  2. For non-project resources, use a non-project launch configuration type or drop the debug support call
  3. Check the resource type in the extension helper and conditionally skip project-type debug support

Example fix

// before
var redis = builder.AddRedis("redis");
redis.WithDebugSupport(launchProfile, KnownLaunchConfigurationTypes.DotnetProject);
// after
var api = builder.AddProject<Projects.Api>("api");
api.WithDebugSupport(launchProfile, KnownLaunchConfigurationTypes.DotnetProject);
Defensive patterns

Strategy: validation

Validate before calling

bool isProjectType = resource is ProjectResource && resource.TryGetProjectMetadata(out _);
if (debugSupport is not null && KnownLaunchConfigurationTypes.IsProject(debugSupport.LaunchConfigurationType) && !isProjectType)
  throw new InvalidOperationException("Project debug launch support requires a project resource.");

Type guard

bool IsProjectResource(IResource r) => r.Annotations.Any(a => a is IProjectMetadata);

Try / catch

try { await CreateLaunchConfigurationsAsync(context, ct); } catch (FailedToApplyEnvironmentException ex) when (ex.Message.Contains("WithDebugSupport")) { /* retry without project debug support or fix resource type */ }

Prevention

When it happens

Trigger: Calling WithDebugSupport on a container or executable resource with the .NET project launch configuration type (KnownLaunchConfigurationTypes.IsProject true) while the resource has no ProjectResourceAnnotation/project metadata.

Common situations: Copy-pasted WithDebugSupport calls from project resources applied to containers/executables; generic helper extension applying debug support to arbitrary resources.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/ExecutableLaunchRecipe.cs:380

            resource.WorkingDirectory,
            context.Decision.Mechanism,
            executableArguments.Count > 0 ? executableArguments : null,
            context.ExecutionConfiguration.EnvironmentVariables,
            launchConfigurations,
            displayArguments);
    }

    private static async Task<IReadOnlyList<JsonElement>> CreateLaunchConfigurationsAsync(ExecutableLaunchContext context)
    {
        if (context.Decision.DebugSupport is not { } debugSupport)
        {
            return [];
        }

        if (KnownLaunchConfigurationTypes.IsProject(debugSupport.LaunchConfigurationType) &&
            !context.Resource.TryGetProjectMetadata(out _))
        {
            throw new FailedToApplyEnvironmentException(
                $"Resource '{context.Resource.Name}' declares \"{debugSupport.LaunchConfigurationType}\" debug launch support (WithDebugSupport) but has no project metadata. " +
                $"The \"{debugSupport.LaunchConfigurationType}\" launch configuration type is reserved for .NET project resources; use a resource that carries {nameof(IProjectMetadata)} or a different launch configuration type.");
        }

        var launchConfiguration = await ProduceLaunchConfigurationAsync(context, debugSupport).ConfigureAwait(false);
        return [launchConfiguration];
    }

    internal static async Task<JsonElement> ProduceLaunchConfigurationAsync(
        ExecutableLaunchContext context,
        SupportsDebuggingAnnotation debugSupport)
    {
        try
        {
            var callbackContext = new LaunchConfigurationCallbackContext(
                context.Decision.LaunchMode,
                context.Resource,
                context.ExecutionConfiguration.EnvironmentVariables.ToDictionary(

View on GitHub (pinned to 25830f84bd)