microsoft/aspire · error · InvalidOperationException

Compute environment for resource

Error message

Compute environment for resource '{Target.Name}' must be an AzureCognitiveServicesProjectResource to deploy as hosted agent.

What it means

The hosted agent's deployment target annotation exists but its ComputeEnvironment is not an AzureCognitiveServicesProjectResource. AzureHostedAgentResource can only deploy agents into an Azure AI Foundry (Cognitive Services) project, so the pipeline step annotation casts the compute environment and throws this InvalidOperationException when the cast fails.

Solutions

Move the target resource into an AzureCognitiveServicesProjectResource-based environment (the Foundry project's compute environment) so its deployment annotation's ComputeEnvironment is a Foundry project
Remove the target from the wrong compute environment (e.g. ACA environment) and re-add it to the Foundry project environment
Verify with `Target.GetDeploymentTargetAnnotation()?.ComputeEnvironment` in a debug session which environment the target is actually bound to

Example fix

// before: target deployed to ACA environment
var aca = builder.AddAzureContainerAppEnvironment("env");
var agent = builder.AddHostedAgent("my-agent", projectIn(aca));
// after: target deployed in the Foundry project environment
var foundry = builder.AddAzureCognitiveServicesProject("foundry");
var agent = builder.AddHostedAgent("my-agent", projectIn(foundry));

Defensive patterns

Strategy: validation

Validate before calling

// Verify the compute environment type before deploy:
var annotation = target.GetDeploymentTargetAnnotation();
var isFoundryProject = annotation?.ComputeEnvironment is AzureCognitiveServicesProjectResource;
if (!isFoundryProject)
{
    throw new InvalidOperationException($"{target.Name} is bound to {annotation?.ComputeEnvironment?.GetType().Name ?? "no"} environment; a Foundry project environment is required.");
}

Type guard

bool IsFoundryHostedTarget(IResource target) =>
    target.GetDeploymentTargetAnnotation()?.ComputeEnvironment is AzureCognitiveServicesProjectResource;

Try / catch

try
{
    // run deploy pipeline
}
catch (InvalidOperationException ex) when (ex.Message.Contains("must be an AzureCognitiveServicesProjectResource"))
{
    // re-wire the target resource into the Foundry project environment
}

Prevention

Use one compute environment per deployment story; keep hosted-agent targets only in Foundry project environments
When multiple environments exist, explicitly attach each target to the intended one instead of relying on defaults
Code-review AppHost changes that move resources between environments when hosted agents are involved

When it happens

Trigger: The target resource's deployment target annotation was created by a different environment type (e.g. Azure Container Apps environment, plain container environment), so `deploymentAnnotation.ComputeEnvironment as AzureCognitiveServicesProjectResource` yields null while running publish/deploy.

Common situations: The target project/container is registered in a ContainerApp environment (or another publish environment) instead of a Foundry project environment; the app model has multiple environments and the target picked up the wrong one; copy-pasted AppHost code wires the agent to a resource deployed to ACA.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

{
    internal const string DefaultResponsesProtocolVersion = "2.0.0";

    /// <summary>
    /// Creates a new instance of the <see cref="AzureHostedAgentResource"/> class.
    /// </summary>
    public AzureHostedAgentResource([ResourceName] string name, IResource target, Action<HostedAgentConfiguration>? configure = null) : base(name)
    {
        ArgumentNullException.ThrowIfNull(target);
        Target = target;
        Configure = configure;
        Annotations.Add(new ManifestPublishingCallbackAnnotation(PublishAsync));
        // Set up steps for deploying this particular hosted agent
        Annotations.Add(new PipelineStepAnnotation(async (ctx) =>
        {
            List<PipelineStep> steps = [];
            var deploymentAnnotation = Target.GetDeploymentTargetAnnotation() ?? throw new InvalidOperationException($"Deployment target annotation is required on resource '{Target.Name}' to deploy as hosted agent.");
            var project = deploymentAnnotation.ComputeEnvironment as AzureCognitiveServicesProjectResource
                ?? throw new InvalidOperationException($"Compute environment for resource '{Target.Name}' must be an AzureCognitiveServicesProjectResource to deploy as hosted agent.");

            // Create a step to deploy container as agent
            var agentDeployStep = new PipelineStep
            {
                Name = $"deploy-{Name}",
                Action = async (ctx) =>
                {
                    var version = await DeployAsync(ctx, project).ConfigureAwait(false);
                    ctx.ReportingStep.Log(LogLevel.Information, new MarkdownString($"Successfully deployed **{Name}** as Hosted Agent (version {version})"));
                    Version.Set(version.Version);
                },
                Tags = [WellKnownPipelineTags.DeployCompute],
                RequiredBySteps = [WellKnownPipelineSteps.Deploy],
                Resource = this,
                DependsOnSteps = [WellKnownPipelineSteps.DeployPrereq, AzureEnvironmentResource.ProvisionInfrastructureStepName]
            };
            steps.Add(agentDeployStep);

View on GitHub (pinned to 25830f84bd)