microsoft/aspire · error · InvalidOperationException

Unable to create hosted agent for resource

Error message

Unable to create hosted agent for resource '{resource.Name}' because it is not a container, executable, or project resource.

What it means

ConfigurePublishMode only supports converting container, executable, and project resources into hosted agents; any other resource type reaches the final else branch and throws this InvalidOperationException. The library cannot represent arbitrary resources as Foundry hosted agents.

Solutions

  1. Call ConfigureAsHostedAgent only on container, executable, or project resources
  2. Move the extension call to the correct resource builder (the agent's host app, not its dependencies)
  3. If the resource is a custom type, wrap it in a container or project resource first
  4. Check loops/composition helpers that may apply the extension to every resource

Example fix

// before
builder.AddRedis("cache").ConfigureAsHostedAgent(project, ...); // unsupported type
// after
builder.AddProject<Projects.AgentHost>("agent-host").ConfigureAsHostedAgent(project, ...);
Defensive patterns

Strategy: validation

Validate before calling

if (resource is not (ContainerResource or ExecutableResource or ProjectResource))
    throw new InvalidOperationException($"'{resource.Name}' must be a container, executable, or project resource to be a hosted agent.");

Type guard

static bool CanBeHostedAgent(IResource r) => r is ContainerResource or ExecutableResource or ProjectResource;

Try / catch

try
{
    builder.ConfigureAsHostedAgent(project, protocol, ...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("not a container, executable, or project resource"))
{
    logger.LogError(ex, "Apply ConfigureAsHostedAgent to the app resource, not its dependencies.");
    throw;
}

Prevention

When it happens

Trigger: Calling ConfigureAsHostedAgent on a resource that is not a ContainerResource, ExecutableResource, or ProjectResource (e.g. a plain CustomResource, connection-string resource, or parameter resource).

Common situations: Applying the hosted-agent extension to the wrong builder (e.g. a database or parameter resource instead of the app service itself); refactoring that changed a resource's type; applying a generic extension to all resources in a loop.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs:498

            builder.ApplicationBuilder.CreateResourceBuilder(executableResource)
                .PublishAsDockerFile();

            if (builder.ApplicationBuilder.TryCreateResourceBuilder(resource.Name, out containerResourceBuilder))
            {
                target = containerResourceBuilder.Resource;
            }
            else
            {
                throw new InvalidOperationException($"Unable to create hosted agent for resource '{resource.Name}' because it could not be converted to a container resource.");
            }
        }
        else if (resource is ProjectResource)
        {
            target = resource;
        }
        else
        {
            throw new InvalidOperationException($"Unable to create hosted agent for resource '{resource.Name}' because it is not a container, executable, or project resource.");
        }

        EnsureDefaultHostedAgentEndpoint(builder, target);

        if (target is ProjectResource projectTarget)
        {
            // Foundry hosted agents are containerized and the platform owns the listening port contract.
            // Keep the user's local endpoint metadata intact, but do not emit project endpoint variables
            // such as ASPNETCORE_URLS/HTTP_PORTS because they require EndpointProperty.TargetPort, which
            // Foundry hosted-agent deployment endpoints intentionally do not support.
            builder.ApplicationBuilder.CreateResourceBuilder(projectTarget)
                .WithEndpointsInEnvironment(_ => false);
        }

        // The hosted agent wrapper is not the deployed workload. Apply the Foundry
        // reference to the target so its connection annotations flow into the deployment.
        builder.ApplicationBuilder.CreateResourceBuilder(target)
            .WithReference(project);

View on GitHub (pinned to 25830f84bd)