microsoft/aspire · error · IllegalStateException

getValue is only available on server-returned…

Error message

getValue is only available on server-returned ReferenceExpression instances

What it means

Aspire detects build-only container resources (containers whose image is built in the pipeline, e.g. for static assets) that no other resource consumes. Such containers would never participate in publish or deploy, which almost always indicates a wiring mistake, so ValidateBuildOnlyContainerReferences throws a DistributedApplicationException listing the unconsumed resources and the remedies.

Solutions

1. Reference the container from the consuming resource, e.g. projectBuilder.PublishWithContainerFiles(container, "/dist") or .PublishWithStaticFiles(container).
2. If the container is intentionally unused (e.g. an experiment), remove the AddDockerfile/AddContainer registration.
3. Suppress the check deliberately with builder.Pipeline.DisableBuildOnlyContainerValidation() when the model is known-good.
4. Verify the resource name in the message matches the container you meant to consume; fix typos in the consuming call.

Example fix

// before
var frontend = builder.AddDockerfile("frontend-build", "./frontend");
// after
var frontend = builder.AddDockerfile("frontend-build", "./frontend");
builder.AddProject<Projects.Api>("api")
    .PublishWithContainerFiles(frontend, "/dist");

// C#: ensure every Dockerfile/build container is referenced before execution
var buildContainers = appModel.Resources.Where(r => r.Annotations.OfType<DockerfileBuildAnnotation>().Any()).ToList();
var consumed = appModel.Resources.SelectMany(r => r.Annotations).OfType<ContainerFilesDestinationAnnotation>().Select(a => a.SourceResource.Name).ToHashSet();
var orphaned = buildContainers.Where(c => !consumed.Contains(c.Name)).ToList();
if (orphaned.Count > 0) throw new InvalidOperationException($"Unconsumed build containers: {string.Join(", ", orphaned.Select(c => c.Name))}");

try
{
    await pipeline.ExecuteAsync(model);
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("Build-only container"))
{
    logger.LogError(ex, "Unconsumed build-only container: {Message}", ex.Message);
}

When it happens

Trigger: Adding a container via builder.AddDockerfile/AddContainer intended only as a build artifact but never referencing it from another resource via PublishWithContainerFiles or PublishWithStaticFiles; renaming/refactoring away the consuming resource.

Common situations: Using Dockerfile-based containers to build frontend assets and forgetting to attach them to the serving project; deleting the resource that consumed the build container; scaffolding a build container while prototyping and never wiring it up.

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

• Union value is of type
• Array params contains empty item
• Cannot use null in a reference expression
• Circular dependency detected in pipeline steps
• Duplicate step name

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Java/Resources/Base.java:233

                for (Object valueProvider : valueProviders) {
                    providers.add(extractValueProvider(valueProvider));
                }
                expression.put("valueProviders", providers);
            }
        }

        Map<String, Object> result = new HashMap<>();
        result.put("$expr", expression);
        return result;
    }

    public String getValue() {
        return getValue(null);
    }

    public String getValue(CancellationToken cancellationToken) {
        if (handle == null || client == null) {
            throw new IllegalStateException("getValue is only available on server-returned ReferenceExpression instances");
        }

        Map<String, Object> reqArgs = new HashMap<>();
        reqArgs.put("context", AspireClient.serializeValue(handle));
        if (cancellationToken != null) {
            reqArgs.put("cancellationToken", cancellationToken);
        }

        return (String) client.invokeCapability("Aspire.Hosting.ApplicationModel/getValue", reqArgs);
    }

    public static ReferenceExpression refExpr(String format, Object... valueProviders) {
        return new ReferenceExpression(format, valueProviders);
    }

    public static ReferenceExpression createConditional(Object condition, String matchValue, ReferenceExpression whenTrue, ReferenceExpression whenFalse) {
        return new ReferenceExpression(condition, matchValue, whenTrue, whenFalse);
    }

View on GitHub (pinned to 25830f84bd)