{"record":{"id":"dca0c62b7ec54591","repo":"microsoft/aspire","slug":"cannot-set-entrypoint-python-environment-annotation-with","errorCode":null,"errorMessage":"Cannot set entrypoint: Python environment annotation with virtual environment not found.","messagePattern":"Cannot set entrypoint: Python environment annotation with virtual environment not found\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs","lineNumber":1046,"sourceCode":"    /// Change a Python app from running a script to running a module:\n    /// <code lang=\"csharp\">\n    /// var python = builder.AddPythonScript(\"api\", \"../python-api\", \"main.py\")\n    ///     .WithEntrypoint(EntrypointType.Module, \"uvicorn\")\n    ///     .WithArgs(\"main:app\", \"--reload\");\n    /// </code>\n    /// </example>\n    [AspireExport]\n    public static IResourceBuilder<T> WithEntrypoint<T>(\n        this IResourceBuilder<T> builder, EntrypointType entrypointType, string entrypoint) where T : PythonAppResource\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n        ArgumentException.ThrowIfNullOrEmpty(entrypoint);\n\n        // Get or create the virtual environment from the annotation\n        if (!builder.Resource.TryGetLastAnnotation<PythonEnvironmentAnnotation>(out var pythonEnv) ||\n            pythonEnv.VirtualEnvironment is null)\n        {\n            throw new InvalidOperationException(\"Cannot set entrypoint: Python environment annotation with virtual environment not found.\");\n        }\n\n        var virtualEnvironment = pythonEnv.VirtualEnvironment;\n\n        // Determine the new command based on entrypoint type\n        var command = entrypointType switch\n        {\n            EntrypointType.Executable => virtualEnvironment.GetExecutable(entrypoint),\n            EntrypointType.Script or EntrypointType.Module => virtualEnvironment.GetExecutable(\"python\"),\n            _ => throw new ArgumentOutOfRangeException(nameof(entrypointType), entrypointType, \"Invalid entrypoint type.\")\n        };\n\n        // Update the command inline\n        builder.WithCommand(command);\n        builder.WithAnnotation(new PythonEntrypointAnnotation\n        {\n            Type = entrypointType,\n            Entrypoint = entrypoint","sourceCodeStart":1028,"sourceCodeEnd":1064,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs#L1028-L1064","documentation":"WithEntrypoint lets you change a Python app's entrypoint after creation, but it needs the VirtualEnvironment stored in PythonEnvironmentAnnotation (typically set by a prior WithVirtualEnvironment call) to compute the new command. If the annotation is missing or its VirtualEnvironment is null, it throws InvalidOperationException.","triggerScenarios":"Calling WithEntrypoint on a Python resource without first calling WithVirtualEnvironment (or after a call that failed to register PythonEnvironmentAnnotation with a non-null VirtualEnvironment).","commonSituations":"Changing entrypoints on resources that never got a virtual environment configured; ordering mistakes where WithEntrypoint precedes WithVirtualEnvironment in the chain; failed WithVirtualEnvironment setup swallowed earlier.","solutions":["Call WithVirtualEnvironment before WithEntrypoint so the PythonEnvironmentAnnotation is populated.","Confirm the earlier WithVirtualEnvironment call succeeded (no swallowed exception).","Verify you are calling WithEntrypoint on the same resource builder that has the virtual environment configured.","If no venv is intended, use the base app APIs (AddPythonApp) instead of WithEntrypoint."],"exampleFix":"// before\nvar py = builder.AddPythonApp(\"app\", \"main.py\");\npy.WithEntrypoint(EntrypointType.Script, \"other.py\"); // missing venv\n// after\nvar py = builder.AddPythonApp(\"app\", \"main.py\");\npy.WithVirtualEnvironment(\".venv\");\npy.WithEntrypoint(EntrypointType.Script, \"other.py\");","handlingStrategy":"type-guard","validationCode":"bool venvReady = pyApp.Resource.TryGetLastAnnotation<PythonEnvironmentAnnotation>(out var env) && env?.VirtualEnvironment is not null;","typeGuard":"static bool HasVirtualEnvironment(IResource resource) =>\n    resource.TryGetLastAnnotation<PythonEnvironmentAnnotation>(out var env) && env.VirtualEnvironment is not null;","tryCatchPattern":"try\n{\n    pyApp.WithEntrypoint(EntrypointType.Script, \"other.py\");\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"virtual environment not found\"))\n{\n    logger.LogError(ex, \"Call WithVirtualEnvironment before WithEntrypoint.\");\n}","preventionTips":["Always call WithVirtualEnvironment before WithEntrypoint.","Check that the earlier WithVirtualEnvironment call did not fail silently.","Keep all Python builder customizations on the same resource builder instance."],"tags":["csharp","aspire","python","virtualenv","ordering"],"backgroundTag":"invalid-state-transition","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}