microsoft/aspire · error · InvalidOperationException

Resource ' ' is configured to publish as a Kubernetes…

Error message

Resource '{r.Name}' is configured to publish as a Kubernetes service, but there are no 'KubernetesEnvironmentResource' resources or Kubernetes-backed compute environments. Ensure you have added one by calling 'AddKubernetesEnvironment'.

What it means

A compute resource carries a KubernetesServiceCustomizationAnnotation but the application model contains no KubernetesEnvironmentResource (no AddKubernetesEnvironment call). Publishing cannot place the resource anywhere, so the model callback throws InvalidOperationException during publish-time validation.

Solutions

Add builder.AddKubernetesEnvironment("kubernetes") to the AppHost before publishing.
Remove the Kubernetes-specific customization calls if Kubernetes publishing is not intended.
Verify the environment is added in Program.cs of the AppHost project.

Example fix

// before
var k8s = builder.AddKubernetesEnvironment("env"); // missing
builder.AddProject<Projects.Api>("api").WithReplicas(3); // Kubernetes customization
// after
builder.AddKubernetesEnvironment("env");
builder.AddProject<Projects.Api>("api").WithReplicas(3);

Defensive patterns

Strategy: validation

Validate before calling

if (!builder.Resources.OfType<KubernetesEnvironmentResource>().Any()) throw new InvalidOperationException("Add AddKubernetesEnvironment before Kubernetes customizations.");

Try / catch

try { appHostBuilder.Build(); } catch (InvalidOperationException ex) when (ex.Message.Contains("AddKubernetesEnvironment")) { /* fix model and rebuild */ }

Prevention

Always call AddKubernetesEnvironment in the AppHost when using Kubernetes customizations
Keep environment registration at the top of Program.cs
Run a publish locally in CI to catch model errors early

When it happens

Trigger: Calling WithComputeEnvironment/Kubernetes customization methods (e.g. WithReplicas, node affinity, etc.) on a resource while never calling builder.AddKubernetesEnvironment(...), then publishing.

Common situations: Migrating an AppHost from another environment (e.g. Docker) to Kubernetes; a team member added resource-level Kubernetes customizations but forgot to add the environment; deleting the AddKubernetesEnvironment line during refactoring.

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

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesEnvironmentExtensions.cs:58

                {
                    ValidateAndFinalizePersistentVolumeBindings(ctx);

                    if (!ctx.ExecutionContext.IsPublishMode)
                    {
                        return Task.CompletedTask;
                    }

                    var hasKubernetesEnvironment = ctx.Model.Resources.OfType<KubernetesEnvironmentResource>().Any() ||
                        ctx.Model.Resources.OfType<IComputeEnvironmentResource>()
                            .Any(r => r.HasAnnotationOfType<KubernetesEnvironmentAnnotation>());

                    if (!hasKubernetesEnvironment)
                    {
                        foreach (var r in ctx.Model.GetComputeResources())
                        {
                            if (r.HasAnnotationOfType<KubernetesServiceCustomizationAnnotation>())
                            {
                                throw new InvalidOperationException($"Resource '{r.Name}' is configured to publish as a Kubernetes service, but there are no '{nameof(KubernetesEnvironmentResource)}' resources or Kubernetes-backed compute environments. Ensure you have added one by calling '{nameof(AddKubernetesEnvironment)}'.");
                            }
                        }
                    }

                    return Task.CompletedTask;
                },
                dependsOn: WellKnownPipelineSteps.ValidateComputeEnvironments,
                requiredBy: WellKnownPipelineSteps.BeforeStart);
        }

        return builder;
    }

    private static void ValidateAndFinalizePersistentVolumeBindings(PipelineStepContext context)
    {
        var bindings = GetPersistentVolumeBindings(context);

        if (context.ExecutionContext.IsRunMode)

View on GitHub (pinned to 25830f84bd)