microsoft/aspire · error · InvalidOperationException

Unsupported entrypoint type

Error message

Unsupported entrypoint type: {entrypointAnnotation.Type}

What it means

WithVirtualEnvironment maps the stored PythonEntrypointAnnotation.Type to a command via a switch expression. If the annotation carries a Type value outside EntrypointType.Executable/Script/Module, the exhaustive switch falls to the default arm and throws InvalidOperationException.

Solutions

1. Use only documented EntrypointType values (Executable, Script, Module) in your annotation.
2. Align the Aspire.Hosting.Python package version across the solution so enum and switch logic match.
3. If you set the annotation manually, switch to Script/Module/Executable as appropriate.
4. Upgrade the hosting package if the enum value comes from a newer API surface.

Example fix

// before
new PythonEntrypointAnnotation { Type = (EntrypointType)99 }
// after
new PythonEntrypointAnnotation { Type = EntrypointType.Script }

if (resource.TryGetLastAnnotation<PythonEntrypointAnnotation>(out var ann) &&
    ann.Type is not (EntrypointType.Executable or EntrypointType.Script or EntrypointType.Module))
    throw new InvalidOperationException($"Unsupported EntrypointType: {ann.Type}");

static bool IsKnownEntrypointType(EntrypointType t) => t is EntrypointType.Executable or EntrypointType.Script or EntrypointType.Module;

try
{
    pyApp.WithVirtualEnvironment(".venv");
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Unsupported entrypoint type"))
{
    logger.LogError(ex, "Entrypoint annotation carries an unsupported EntrypointType.");
}

When it happens

Trigger: A PythonEntrypointAnnotation with a newly added or manually assigned EntrypointType value not covered by the switch on the resource when WithVirtualEnvironment runs.

Common situations: Library version mismatch where newer EntrypointType members exist; manually constructing PythonEntrypointAnnotation with an unhandled type; future enum additions processed by an older hosting package.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

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

Appendix: source

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

        // 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
        if (!createIfNotExists)
        {
            RemoveVenvCreator(builder);
        }

        return builder;
    }

View on GitHub (pinned to 25830f84bd)