microsoft/aspire · error · InvalidOperationException

Unable to create hosted agent for resource

Error message

Unable to create hosted agent for resource '{resource.Name}' because it could not be converted to a container resource.

What it means

During publish-mode configuration, ConfigurePublishMode attempts to obtain a builder for the target resource so it can be converted to a container-backed hosted agent. If the resource is a container resource but TryCreateResourceBuilder cannot create a builder for it, the method throws this InvalidOperationException.

Solutions

  1. Ensure the resource was added via the standard IResourceBuilder APIs on the same ApplicationBuilder
  2. Convert the resource to a standard ContainerResource usage or a project/executable resource supported by hosted agents
  3. Check that the resource name matches the one registered in the ApplicationBuilder
  4. If using a custom resource type, implement conversion to ContainerResource or register it in a way TryCreateResourceBuilder can resolve

Example fix

// before
var custom = new MyWeirdContainer("agent");
builder.AddResource(custom).ConfigureAsHostedAgent(...); // builder lookup fails
// after
builder.AddContainer("agent", image, tag).ConfigureAsHostedAgent(project, ...);
Defensive patterns

Strategy: validation

Validate before calling

if (resource is ContainerResource && !builder.ApplicationBuilder.TryCreateResourceBuilder(resource.Name, out _))
    throw new InvalidOperationException($"Resource '{resource.Name}' must be registered via the standard ApplicationBuilder to become a hosted agent.");

Type guard

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

Try / catch

try
{
    builder.ConfigureAsHostedAgent(project, protocol, ...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("could not be converted to a container resource"))
{
    logger.LogError(ex, "Resource must be added via standard builder APIs.");
    throw;
}

Prevention

When it happens

Trigger: Calling ConfigureAsHostedAgent on a resource that is a container resource whose builder cannot be recreated by TryCreateResourceBuilder (e.g. resource was added outside the application builder's tracked resources, or a custom container-derived resource with an unresolvable name).

Common situations: Custom resource types deriving from container semantics that the extension cannot map; resources added via unusual/custom builder paths; duplicate or mutated resource names breaking the builder lookup.

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/0989cce8d80c58f1. Report an issue: GitHub.

Appendix: source

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

        }
        else if (builder.ApplicationBuilder.TryCreateResourceBuilder<ContainerResource>(resource.Name, out var containerResourceBuilder))
        {
            target = containerResourceBuilder.Resource;
        }
        else if (resource is ExecutableResource executableResource)
        {
            // Ensure we have a container resource to deploy.
            // ExecutableResource needs PublishAsDockerFile() to convert it into a container resource at this stage.
            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

View on GitHub (pinned to 25830f84bd)