microsoft/aspire · error · InvalidOperationException

Cannot configure debugging: Python entrypoint annotation…

Error message

Cannot configure debugging: Python entrypoint annotation not found.

What it means

WithDebugging attaches PythonExecutableDebuggableAnnotation and then reads PythonEntrypointAnnotation to know whether the entrypoint is a script, module, or executable so it can wire debug support. Without that annotation the debug configuration cannot proceed, so it throws InvalidOperationException.

Solutions

1. Configure the app via AddPythonApp or AddPythonExecutable before calling WithDebugging.
2. Verify the chain targets the same resource that has the entrypoint annotation.
3. If the resource is manual, add a PythonEntrypointAnnotation with correct EntrypointType/Entrypoint first.
4. Reorder builder calls so entrypoint configuration precedes debugging configuration.

Example fix

// before
var py = builder.AddPythonResource("app");
py.WithDebugging();
// after
var py = builder.AddPythonApp("app", "main.py");
py.WithDebugging();

bool canDebug = pyApp.Resource.HasAnnotation<PythonEntrypointAnnotation>();

static bool IsDebuggableCandidate(IResource resource) => resource.TryGetLastAnnotation<PythonEntrypointAnnotation>(out _);

try
{
    pyApp.WithDebugging();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Cannot configure debugging"))
{
    logger.LogError(ex, "WithDebugging requires an entrypoint from AddPythonApp/AddPythonExecutable.");
}

When it happens

Trigger: Calling WithDebugging on a Python resource that was not created through AddPythonApp/AddPythonExecutable (no PythonEntrypointAnnotation), or on the wrong builder instance.

Common situations: Manually built PythonResource instances; chaining WithDebugging before the entrypoint-configuring call; copying sample code onto a resource of a different type.

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

• Cannot update virtual environment: Python entrypoint…
• Array params contains empty item
• Array params contains null item
• Cannot set entrypoint: Python environment annotation with…
• Invalid entrypoint type.

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

Appendix: source

Thrown at src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs:935

    /// </para>
    /// <para>
    /// The debug configuration includes the Python interpreter path from the virtual environment,
    /// the program or module to debug, and appropriate launch settings.
    /// </para>
    /// </remarks>
    [AspireExport]
    public static IResourceBuilder<T> WithDebugging<T>(
        this IResourceBuilder<T> builder) where T : PythonAppResource
    {
        ArgumentNullException.ThrowIfNull(builder);

        // Add the annotation that marks this resource as debuggable
        builder.WithAnnotation(new PythonExecutableDebuggableAnnotation());

        // Get the entrypoint annotation to determine how to configure debugging
        if (!builder.Resource.TryGetLastAnnotation<PythonEntrypointAnnotation>(out var entrypointAnnotation))
        {
            throw new InvalidOperationException("Cannot configure debugging: Python entrypoint annotation not found.");
        }

        var entrypointType = entrypointAnnotation.Type;
        var entrypoint = entrypointAnnotation.Entrypoint;

        builder.WithDebugSupport(
            mode =>
            {
                // Compute paths inside the lambda so a later WithWorkingDirectory(...) override is respected.
                var workingDirectory = builder.Resource.WorkingDirectory;

                string programPath;
                string module;

                if (entrypointType == EntrypointType.Script)
                {
                    programPath = Path.GetFullPath(entrypoint, workingDirectory);
                    module = string.Empty;

View on GitHub (pinned to 25830f84bd)