microsoft/aspire · error · ArgumentOutOfRangeException

Invalid entrypoint type.

Error message

Invalid entrypoint type.

What it means

WithEntrypoint maps the supplied EntrypointType to a command via a switch expression covering Executable, Script, and Module. Any other value reaches the default arm and throws ArgumentOutOfRangeException naming entrypointType.

Solutions

1. Pass a valid EntrypointType: EntrypointType.Executable, EntrypointType.Script, or EntrypointType.Module.
2. Validate any config-driven enum value with Enum.IsDefined before casting.
3. Align Aspire.Hosting.Python package versions across projects.
4. Parse with Enum.TryParse<EntrypointType> and reject unknown values early.

Example fix

// before
var type = (EntrypointType)configValue; // 7, undefined
py.WithEntrypoint(type, "tool.py");
// after
var type = Enum.IsDefined(typeof(EntrypointType), configValue) ? (EntrypointType)configValue : EntrypointType.Script;
py.WithEntrypoint(type, "tool.py");

if (!Enum.IsDefined(entrypointType))
    throw new ArgumentOutOfRangeException(nameof(entrypointType), $"Unsupported EntrypointType: {entrypointType}");

static bool TryParseEntrypointType(object raw, out EntrypointType value)
{
    value = default;
    return raw is int i && Enum.IsDefined(typeof(EntrypointType), i)
        ? (value = (EntrypointType)i) is var _
        : Enum.TryParse(raw?.ToString(), out value) && Enum.IsDefined(value);
}

try
{
    pyApp.WithEntrypoint(entrypointType, entrypoint);
}
catch (ArgumentOutOfRangeException ex)
{
    logger.LogError(ex, "entrypointType must be Executable, Script, or Module.");
}

When it happens

Trigger: Passing an EntrypointType value outside the three supported members to WithEntrypoint — typically from an invalid cast, uninitialized enum value, or a value from a mismatched package version.

Common situations: Casting int values to EntrypointType from external config; deserializing enum from user input; version drift between client code and the Aspire.Hosting.Python package introducing new enum members.

Understand the failure class

Background: "invalid argument", "unknown mode", "not supported": invalid enum-like argument errors explained — this error's family across 19 libraries.

Related errors

• Unsupported 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/ef1af05366b39587. Report an issue: GitHub.

Appendix: source

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

    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(entrypoint);

        // Get or create the virtual environment from the annotation
        if (!builder.Resource.TryGetLastAnnotation<PythonEnvironmentAnnotation>(out var pythonEnv) ||
            pythonEnv.VirtualEnvironment is null)
        {
            throw new InvalidOperationException("Cannot set entrypoint: Python environment annotation with virtual environment not found.");
        }

        var virtualEnvironment = pythonEnv.VirtualEnvironment;

        // Determine the new command based on entrypoint type
        var command = entrypointType switch
        {
            EntrypointType.Executable => virtualEnvironment.GetExecutable(entrypoint),
            EntrypointType.Script or EntrypointType.Module => virtualEnvironment.GetExecutable("python"),
            _ => throw new ArgumentOutOfRangeException(nameof(entrypointType), entrypointType, "Invalid entrypoint type.")
        };

        // Update the command inline
        builder.WithCommand(command);
        builder.WithAnnotation(new PythonEntrypointAnnotation
        {
            Type = entrypointType,
            Entrypoint = entrypoint
        },
        ResourceAnnotationMutationBehavior.Replace);

        // Arguments already registered for the previous entrypoint may be invalid for the replacement. Keep this
        // clear in the ordinary argument segment so arguments registered after WithEntrypoint are preserved.
        builder.WithArgs(static context => context.Args.Clear());

        builder.WithLaunchToolArgs(static context =>
        {
            if (!context.Resource.TryGetLastAnnotation<PythonEntrypointAnnotation>(out var existingAnnotation))

View on GitHub (pinned to 25830f84bd)