microsoft/aspire · error · InvalidOperationException

Cannot update virtual environment: Python entrypoint…

Error message

Cannot update virtual environment: Python entrypoint annotation not found.

What it means

WithVirtualEnvironment rewrites the resource's command to point at the virtual environment's interpreter/executable. It first looks up the PythonEntrypointAnnotation on the resource; if the annotation is absent it throws InvalidOperationException because it cannot know how to rebase the command.

Solutions

1. Call AddPythonApp or AddPythonExecutable first so the PythonEntrypointAnnotation is registered, then call WithVirtualEnvironment.
2. Verify you are chaining on the correct builder/resource instance.
3. If constructing the resource manually, add a PythonEntrypointAnnotation with the correct EntrypointType before calling WithVirtualEnvironment.
4. Check ordering: WithVirtualEnvironment depends on prior entrypoint configuration.

Example fix

// before
var py = builder.AddPythonApp("app", "main.py"); // then WithVirtualEnvironment on wrong resource
// after
var py = builder.AddPythonApp("app", "main.py");
py.WithVirtualEnvironment(".venv"); // chained on the same builder

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

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

try
{
    pyApp.WithVirtualEnvironment(".venv");
}
catch (InvalidOperationException ex) when (ex.Message.Contains("entrypoint annotation not found"))
{
    logger.LogError(ex, "Resource was not created via AddPythonApp/AddPythonExecutable.");
}

When it happens

Trigger: Calling WithVirtualEnvironment on a builder whose resource was not created via the Python app entrypoint APIs (AddPythonApp/AddPythonExecutable), so no PythonEntrypointAnnotation exists.

Common situations: Creating a PythonResource manually with AddResource plus annotations; calling WithVirtualEnvironment before AddPythonApp ran; applying it to a different resource type that lacks the entrypoint annotation.

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 configure debugging: Python entrypoint annotation…
• 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/93b775263dd1de6a. Report an issue: GitHub.

Appendix: source

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

    /// </example>
    [AspireExport]
    public static IResourceBuilder<T> WithVirtualEnvironment<T>(
        this IResourceBuilder<T> builder, string virtualEnvironmentPath, bool createIfNotExists = true) where T : PythonAppResource
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(virtualEnvironmentPath);

        // Use the provided path verbatim - resolve relative paths against the app working directory
        var resolvedPath = Path.IsPathRooted(virtualEnvironmentPath)
            ? virtualEnvironmentPath
            : Path.GetFullPath(virtualEnvironmentPath, builder.Resource.WorkingDirectory);

        var virtualEnvironment = new VirtualEnvironment(resolvedPath);

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

        // Update the command based on entrypoint type
        string command = entrypointAnnotation.Type switch
        {
            EntrypointType.Executable => virtualEnvironment.GetExecutable(entrypointAnnotation.Entrypoint),
            EntrypointType.Script or EntrypointType.Module => virtualEnvironment.GetExecutable("python"),
            _ => throw new InvalidOperationException($"Unsupported entrypoint type: {entrypointAnnotation.Type}")
        };

        builder.WithCommand(command);
        builder.WithPythonEnvironment(env =>
        {
            env.VirtualEnvironment = virtualEnvironment;
            env.CreateVenvIfNotExists = createIfNotExists;
        });

        // If createIfNotExists is false, remove venv creator

View on GitHub (pinned to 25830f84bd)