microsoft/aspire · error · InvalidOperationException

Resource ' ' does not declare debug launch support. Call…

Error message

Resource '{resource.Name}' does not declare debug launch support. Call ResourceBuilderExtensions.WithDebugSupport on the resource first. Note that it only adds the annotation in run mode.

What it means

CreateLaunchConfigurationAsync requires the resource to carry a SupportsDebuggingAnnotation, which is what provides the launch-configuration producer (debugger path, args, etc.). If no such annotation exists it throws InvalidOperationException telling the developer to register debug support via ResourceBuilderExtensions.WithDebugSupport, noting that the annotation is only added in run mode.

Solutions

Call .WithDebugSupport(...) on the resource builder before running the app model.
Ensure the code path runs in run mode — request launch configuration only when the app is being run, not published.
Check with resource.TryGetLastAnnotation<SupportsDebuggingAnnotation> before calling, and fall back to a normal (non-debug) start.

Example fix

// before
var resource = builder.AddExecutable("tool", "tool", ".");
var cfg = await resource.Resource.CreateLaunchConfigurationAsync(context);
// after
var resource = builder.AddExecutable("tool", "tool", ".").WithDebugSupport(...);
var cfg = await resource.Resource.CreateLaunchConfigurationAsync(context);

Defensive patterns

Strategy: type-guard

Validate before calling

if (!resource.TryGetLastAnnotation<SupportsDebuggingAnnotation>(out _))
{
    logger.LogWarning("Resource {Name} has no debug support; skipping debug launch config", resource.Name);
    return null; // fall back to normal start
}

Type guard

static bool HasDebugSupport(IResource resource) =>
    resource.TryGetLastAnnotation<SupportsDebuggingAnnotation>(out _);

Try / catch

try
{
    var cfg = await resource.CreateLaunchConfigurationAsync(context, ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("debug launch support"))
{
    logger.LogWarning(ex, "No debug support for {Name}; starting without debugger", resource.Name);
    return null;
}

Prevention

Call .WithDebugSupport(...) on every resource type that must be debuggable.
Only request launch configuration in run mode — the annotation is not added in publish mode.
Wrap launch-config acquisition in a helper that checks SupportsDebuggingAnnotation first.
Add a model-level test asserting debug resources carry the annotation.

When it happens

Trigger: Calling CreateLaunchConfigurationAsync for a resource whose builder never called WithDebugSupport, or calling it outside run mode (publish mode, design time) where WithDebugSupport deliberately does not add the annotation.

Common situations: Custom project/Executable resource types without debug wiring; tests that build the resource model in publish mode then request launch configuration; calling the API before the resource's annotations were applied during startup ordering.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/DebugSupportExtensions.cs:181

    /// </remarks>
    internal static Task<object> CreateLaunchConfigurationAsync(
        this IResource resource,
        LaunchConfigurationCallbackContext context)
    {
        ArgumentNullException.ThrowIfNull(resource);
        ArgumentNullException.ThrowIfNull(context);

        if (!ReferenceEquals(resource, context.Resource))
        {
            throw new ArgumentException(
                $"The launch configuration callback context belongs to resource '{context.Resource.Name}', " +
                $"but launch configuration was requested for resource '{resource.Name}'.",
                nameof(context));
        }

        if (!resource.TryGetLastAnnotation<SupportsDebuggingAnnotation>(out var supportsDebuggingAnnotation))
        {
            throw new InvalidOperationException(
                $"Resource '{resource.Name}' does not declare debug launch support. " +
                $"Call {nameof(ResourceBuilderExtensions.WithDebugSupport)} on the resource first. " +
                $"Note that it only adds the annotation in run mode.");
        }

        return supportsDebuggingAnnotation.LaunchConfigurationProducer(context);
    }

    private static string[]? GetSupportedLaunchConfigurations(IConfiguration configuration)
    {
        return DebugSessionInfoParser.TryGetSupportedLaunchConfigurations(
            configuration[KnownConfigNames.DebugSessionInfo],
            out var supportedLaunchConfigurations)
                ? supportedLaunchConfigurations
                : null;
    }
}

View on GitHub (pinned to 25830f84bd)