microsoft/aspire · error · InvalidOperationException

Resource ' ' is configured to publish as a Docker Compose…

Error message

Resource '{r.Name}' is configured to publish as a Docker Compose service, but there are no 'DockerComposeEnvironmentResource' resources. Ensure you have added one by calling 'AddDockerComposeEnvironment'.

What it means

During publish, this infrastructure callback verifies that any compute resource carrying a DockerComposeServiceCustomizationAnnotation actually has a DockerComposeEnvironmentResource in the model. If none exists, the customization cannot be applied and an InvalidOperationException is thrown naming the offending resource. It catches compose customizations applied without ever adding the compose environment.

Solutions

Add a Docker Compose environment before publishing: builder.AddDockerComposeEnvironment("env").
Or remove the compose customization call from the resource if compose publishing is not intended.
Verify ordering — the environment must be added to the same builder/model being published.

Example fix

// before
builder.AddProject<Projects.Api>("api").WithDockerComposeServiceCustomization(c => { });
// (no environment)
// after
builder.AddDockerComposeEnvironment("compose-env");
builder.AddProject<Projects.Api>("api").WithDockerComposeServiceCustomization(c => { });

Defensive patterns

Strategy: validation

Validate before calling

// before publish, verify the environment exists if compose customizations are used
if (model.Resources.OfType<DockerComposeEnvironmentResource>().Any() == false &&
    model.Resources.Any(r => r.HasAnnotationOfType<DockerComposeServiceCustomizationAnnotation>()))
    throw new InvalidOperationException("AddDockerComposeEnvironment must be called before using compose customizations");

Prevention

Call AddDockerComposeEnvironment at the top of the AppHost when targeting compose
Keep environment setup and compose customizations in the same builder configuration
Review removed lines during refactors that may have dropped the environment registration

When it happens

Trigger: Calling WithDockerComposeServiceCustomization (or similar compose-specific APIs) on a resource while the builder never invoked AddDockerComposeEnvironment, then running publish.

Common situations: Copy-pasting code that customizes compose output but omitting the environment setup line; refactoring that removed the AddDockerComposeEnvironment call while leaving customizations; sharing a host module where only one side of the setup was included.

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/b86f61033984bfe1. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Docker/DockerComposeEnvironmentExtensions.cs:48

        {
            builder.Services.AddSingleton<DockerComposePipelineStepMarker>();

            builder.Pipeline.AddStep(
                name: DockerComposePipelineStepMarker.StepName,
                action: ctx =>
                {
                    if (!ctx.ExecutionContext.IsPublishMode)
                    {
                        return Task.CompletedTask;
                    }

                    if (!ctx.Model.Resources.OfType<DockerComposeEnvironmentResource>().Any())
                    {
                        foreach (var r in ctx.Model.GetComputeResources())
                        {
                            if (r.HasAnnotationOfType<DockerComposeServiceCustomizationAnnotation>())
                            {
                                throw new InvalidOperationException($"Resource '{r.Name}' is configured to publish as a Docker Compose service, but there are no '{nameof(DockerComposeEnvironmentResource)}' resources. Ensure you have added one by calling '{nameof(AddDockerComposeEnvironment)}'.");
                            }
                        }
                    }

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

        return builder;
    }

    private sealed class DockerComposePipelineStepMarker
    {
        public const string StepName = "validate-docker-compose";
    }

    /// <summary>

View on GitHub (pinned to 25830f84bd)