{"record":{"id":"704fa05678cc501b","repo":"microsoft/aspire","slug":"deployment-target-annotation-is-required-on-resource-target","errorCode":null,"errorMessage":"Deployment target annotation is required on resource '{Target.Name}' to deploy as hosted agent.","messagePattern":"Deployment target annotation is required on resource '(.+?)' to deploy as hosted agent\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs","lineNumber":43,"sourceCode":"/// </summary>\npublic class AzureHostedAgentResource : Resource, IResourceWithEnvironment\n{\n    internal const string DefaultResponsesProtocolVersion = \"2.0.0\";\n\n    /// <summary>\n    /// Creates a new instance of the <see cref=\"AzureHostedAgentResource\"/> class.\n    /// </summary>\n    public AzureHostedAgentResource([ResourceName] string name, IResource target, Action<HostedAgentConfiguration>? configure = null) : base(name)\n    {\n        ArgumentNullException.ThrowIfNull(target);\n        Target = target;\n        Configure = configure;\n        Annotations.Add(new ManifestPublishingCallbackAnnotation(PublishAsync));\n        // Set up steps for deploying this particular hosted agent\n        Annotations.Add(new PipelineStepAnnotation(async (ctx) =>\n        {\n            List<PipelineStep> steps = [];\n            var deploymentAnnotation = Target.GetDeploymentTargetAnnotation() ?? throw new InvalidOperationException($\"Deployment target annotation is required on resource '{Target.Name}' to deploy as hosted agent.\");\n            var project = deploymentAnnotation.ComputeEnvironment as AzureCognitiveServicesProjectResource\n                ?? throw new InvalidOperationException($\"Compute environment for resource '{Target.Name}' must be an AzureCognitiveServicesProjectResource to deploy as hosted agent.\");\n\n            // Create a step to deploy container as agent\n            var agentDeployStep = new PipelineStep\n            {\n                Name = $\"deploy-{Name}\",\n                Action = async (ctx) =>\n                {\n                    var version = await DeployAsync(ctx, project).ConfigureAwait(false);\n                    ctx.ReportingStep.Log(LogLevel.Information, new MarkdownString($\"Successfully deployed **{Name}** as Hosted Agent (version {version})\"));\n                    Version.Set(version.Version);\n                },\n                Tags = [WellKnownPipelineTags.DeployCompute],\n                RequiredBySteps = [WellKnownPipelineSteps.Deploy],\n                Resource = this,\n                DependsOnSteps = [WellKnownPipelineSteps.DeployPrereq, AzureEnvironmentResource.ProvisionInfrastructureStepName]\n            };","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs#L25-L61","documentation":"An AzureHostedAgentResource wraps a target containerized workload and deploys it as a hosted agent in an Azure AI Foundry project. To know where to deploy, its pipeline step annotation reads the target resource's deployment target annotation, which carries the compute environment. This error is thrown during pipeline step construction when the target resource was never associated with a deployment target.","triggerScenarios":"Creating `new AzureHostedAgentResource(name, target)` (or the AddHostedAgent-style extension) where `target` is a project/container resource that has no deployment target annotation, then running publish/deploy so the PipelineStepAnnotation executes and `Target.GetDeploymentTargetAnnotation()` returns null.","commonSituations":"Forgetting to publish the target project as a container (no AddDockerfileEnvironmentContainerAppHost / PublishAsAzureContainerApp-style wiring); pointing the hosted agent at a bare resource that is only meant for local run mode; wiring the agent before the target is added to a compute environment.","solutions":["Associate the target resource with an Azure compute environment so it gets a deployment target annotation (e.g. publish it as a container app inside the AzureCognitiveServicesProjectResource environment)","Ensure the target passed to AzureHostedAgentResource is a containerized project resource, not a plain Resource","Check that the compute environment resource is created and the target is added to it before the hosted agent's pipeline steps run"],"exampleFix":"// before\nvar agent = builder.AddHostedAgent(\"my-agent\", project); // project has no deployment target\n// after\nvar foundry = builder.AddAzureCognitiveServicesProject(\"foundry\");\nvar project = builder.AddDockerfileEnvironmentContainerAppHost(...).AsFoundryHostedAgentTarget(foundry);\nvar agent = builder.AddHostedAgent(\"my-agent\", project);","handlingStrategy":"validation","validationCode":"// In AppHost code, before creating the hosted agent, assert the target has a deployment target:\nif (target.GetDeploymentTargetAnnotation() is null)\n{\n    throw new InvalidOperationException($\"{target.Name} must be added to a Foundry compute environment before AddHostedAgent.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    // build/publish pipeline that includes the hosted agent steps\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Deployment target annotation is required\"))\n{\n    // surface a targeted message: wire the target into a Foundry project environment\n}","preventionTips":["Always create the AzureCognitiveServicesProjectResource environment first, then register containerized targets in it, then attach hosted agents","Review AppHost diffs that change target/compute-environment wiring for hosted agents","Keep the AddHostedAgent call adjacent to the code that binds the target to the compute environment"],"tags":["azure","foundry","deploy","missing-annotation"],"backgroundTag":"missing-required-config","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"}