{"record":{"id":"fc135f6da70f4897","repo":"microsoft/aspire","slug":"container-image-for-hosted-agent-name-could-not-be-resolved","errorCode":null,"errorMessage":"Container image for hosted agent '{Name}' could not be resolved.","messagePattern":"Container image for hosted agent '(.+?)' could not be resolved\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs","lineNumber":109,"sourceCode":"    /// <summary>\n    /// The fully qualified image name for the hosted agent.\n    /// </summary>\n    public ContainerImageReference Image => new(Target);\n\n    /// <summary>\n    /// The target containerized workload that this hosted agent deploys.\n    /// </summary>\n    public IResource Target { get; }\n\n    /// <summary>\n    /// Convert all dynamic values into concrete values for deployment.\n    /// </summary>\n    private async Task<HostedAgentConfiguration> ToHostedAgentConfigurationAsync(PipelineStepContext context)\n    {\n        var imageName = await ((IValueProvider)Image).GetValueAsync(context.CancellationToken).ConfigureAwait(false);\n        if (string.IsNullOrEmpty(imageName))\n        {\n            throw new InvalidOperationException($\"Container image for hosted agent '{Name}' could not be resolved.\");\n        }\n\n        var def = new HostedAgentConfiguration(imageName)\n        {\n            // ProcessEnvironmentVariableValuesAsync does not resolve values properly in the deploy context\n            EnvironmentVariables = await GetResolvedEnvironmentVariablesAsync(context.ExecutionContext, this, Target, context.Logger, context.CancellationToken).ConfigureAwait(false),\n        };\n        if (Configure is not null)\n        {\n            Configure(def);\n        }\n        EnsureProtocolVersions(def);\n        return def;\n    }\n\n    internal static void EnsureProtocolVersions(HostedAgentConfiguration configuration)\n    {\n        if (configuration.ProtocolVersions.Count == 0)","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs#L91-L127","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the target resource is a containerizable project (or has a Dockerfile) so a container image reference is produced during deploy","Run the full deploy pipeline including build/push steps so the image name is populated before the agent deploy step executes","If Target is a custom resource, implement/provide the container image annotation so ContainerImageReference resolves to a non-empty name","Inspect upstream pipeline step logs for failed image build/push steps that left the image unresolved"],"exampleFix":"// before: bare resource without container image\nvar target = builder.AddResource(\"agent\");\nvar agent = builder.AddHostedAgent(\"my-agent\", target);\n// after: containerized target with a Dockerfile image\nvar target = builder.AddDockerfile(\"agent\", \"./Dockerfile\");\nvar agent = builder.AddHostedAgent(\"my-agent\", target);","handlingStrategy":"validation","validationCode":"// Before deploy, ensure the target produces a container image:\nvar imageRef = new ContainerImageReference(target);\nvar imageName = await ((IValueProvider)imageRef).GetValueAsync(cancellationToken);\nif (string.IsNullOrEmpty(imageName))\n{\n    throw new InvalidOperationException($\"Target '{target.Name}' has no resolvable container image; add a Dockerfile or container image configuration.\");\n}","typeGuard":"bool HasResolvableImage(IResource target) =>\n    target.HasAnnotationOfType<ContainerImageReferenceAnnotation>()\n    || target is ProjectResource; // project resources get image references when containerized","tryCatchPattern":"try\n{\n    // deploy step that creates the hosted agent version\n}\ncatch (InvalidOperationException ex) when (ex.Message.StartsWith(\"Container image for hosted agent\"))\n{\n    // check the build/push steps; fix the target's container image configuration\n}","preventionTips":["Verify `aspire publish` produces an image for the target before wiring it as a hosted agent","Keep build/push pipeline steps enabled so the image name is populated before deploy","Use Dockerfile-based or project-based targets with container publishing configured, never bare custom resources"],"tags":["azure","foundry","container-image","deploy"],"backgroundTag":"empty-required-field","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"}