microsoft/aspire · error · InvalidOperationException

Container image for hosted agent

Error message

Container image for hosted agent '{Name}' could not be resolved.

What it means

Before creating the hosted agent version, Aspire resolves the container image reference of the target resource into a concrete image name via its IValueProvider. If the resolved value is null, empty, or whitespace, the deployment cannot proceed and this InvalidOperationException is thrown.

Solutions

1. Ensure the target resource is a containerizable project (or has a Dockerfile) so a container image reference is produced during deploy
2. Run the full deploy pipeline including build/push steps so the image name is populated before the agent deploy step executes
3. If Target is a custom resource, implement/provide the container image annotation so ContainerImageReference resolves to a non-empty name
4. Inspect upstream pipeline step logs for failed image build/push steps that left the image unresolved

Example fix

// before: bare resource without container image
var target = builder.AddResource("agent");
var agent = builder.AddHostedAgent("my-agent", target);
// after: containerized target with a Dockerfile image
var target = builder.AddDockerfile("agent", "./Dockerfile");
var agent = builder.AddHostedAgent("my-agent", target);

// Before deploy, ensure the target produces a container image:
var imageRef = new ContainerImageReference(target);
var imageName = await ((IValueProvider)imageRef).GetValueAsync(cancellationToken);
if (string.IsNullOrEmpty(imageName))
{
    throw new InvalidOperationException($"Target '{target.Name}' has no resolvable container image; add a Dockerfile or container image configuration.");
}

bool HasResolvableImage(IResource target) =>
    target.HasAnnotationOfType<ContainerImageReferenceAnnotation>()
    || target is ProjectResource; // project resources get image references when containerized

try
{
    // deploy step that creates the hosted agent version
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Container image for hosted agent"))
{
    // check the build/push steps; fix the target's container image configuration
}

When it happens

Trigger: ToHostedAgentConfigurationAsync calls `((IValueProvider)Image).GetValueAsync` and receives an empty string; this happens when the target resource has no publishable container image (e.g. it was never configured with a Dockerfile or container image, or the image name annotation was stripped) and the deploy step runs.

Common situations: The target project is not set up for container publishing so there is no image name at deploy time; a custom IResource was passed as Target and does not produce an image reference; build/push steps failed silently upstream leaving the image value unpopulated; running deploy without the BuildCompute/push pipeline having produced the image.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• AzureEnvironmentResource must be present in the application…
• Compute environment for resource
• Deployment target annotation is required on resource
• Azure AI Search tool
• Azure AI Search tool

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:109

    /// <summary>
    /// The fully qualified image name for the hosted agent.
    /// </summary>
    public ContainerImageReference Image => new(Target);

    /// <summary>
    /// The target containerized workload that this hosted agent deploys.
    /// </summary>
    public IResource Target { get; }

    /// <summary>
    /// Convert all dynamic values into concrete values for deployment.
    /// </summary>
    private async Task<HostedAgentConfiguration> ToHostedAgentConfigurationAsync(PipelineStepContext context)
    {
        var imageName = await ((IValueProvider)Image).GetValueAsync(context.CancellationToken).ConfigureAwait(false);
        if (string.IsNullOrEmpty(imageName))
        {
            throw new InvalidOperationException($"Container image for hosted agent '{Name}' could not be resolved.");
        }

        var def = new HostedAgentConfiguration(imageName)
        {
            // ProcessEnvironmentVariableValuesAsync does not resolve values properly in the deploy context
            EnvironmentVariables = await GetResolvedEnvironmentVariablesAsync(context.ExecutionContext, this, Target, context.Logger, context.CancellationToken).ConfigureAwait(false),
        };
        if (Configure is not null)
        {
            Configure(def);
        }
        EnsureProtocolVersions(def);
        return def;
    }

    internal static void EnsureProtocolVersions(HostedAgentConfiguration configuration)
    {
        if (configuration.ProtocolVersions.Count == 0)

View on GitHub (pinned to 25830f84bd)