microsoft/aspire · error · DistributedApplicationException

Could not create HTTP command for resource

Error message

Could not create HTTP command for resource '{builder.Resource.Name}' as the endpoint with name '{endpoint.EndpointName}' and scheme '{endpoint.Scheme}' is not an HTTP endpoint.

What it means

After the endpoint selector resolves an endpoint, Aspire verifies the endpoint's scheme is http or https before wiring an HTTP command. An endpoint with any other scheme (tcp, custom schemes) cannot be addressed with an HttpRequestMessage, so it throws DistributedApplicationException identifying the endpoint name and scheme.

Solutions

  1. Point the selector at an endpoint declared with scheme http or https
  2. Change the endpoint declaration to use http/https if the endpoint really serves HTTP
  3. If the endpoint is intentionally non-HTTP, use a process command instead of an HTTP command

Example fix

// before
var ep = resource.GetEndpoint("metrics"); // declared scheme: "tcp"
// after
var ep = resource.GetEndpoint("http"); // endpoint declared with scheme "http"
Defensive patterns

Strategy: validation

Validate before calling

var ep = selector();
if (ep is not null && ep.Scheme is not ("http" or "https"))
    throw new InvalidOperationException($"Endpoint '{ep.EndpointName}' must be http/https, was '{ep.Scheme}'");

Type guard

bool IsHttpEndpoint(EndpointReference? ep) => ep?.Scheme is "http" or "https";

Try / catch

try { builder.WithHttpCommand(...); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("is not an HTTP endpoint")) { /* reselect or redeclare endpoint */ }

Prevention

When it happens

Trigger: Creating an HTTP command (WithHttpCommand-style API) whose selector returns an endpoint declared with a non-HTTP scheme, e.g. WithEndpoint(name: "admin", scheme: "tcp") or a custom scheme registered via WithEndpoint(scheme: ...).

Common situations: Selecting an endpoint by name that was defined for raw TCP or another protocol; scheme typos like 'htps'; endpoints shared between an HTTP command and a non-HTTP health probe.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ResourceBuilderExtensions.cs:3688

    /// </remarks>
    [AspireExportIgnore(Reason = "Use the ATS-specific withHttpCommand export.")]
    public static IResourceBuilder<TResource> WithHttpCommand<TResource>(
        this IResourceBuilder<TResource> builder,
        string path,
        string displayName,
        Func<EndpointReference>? endpointSelector,
        string? commandName = null,
        HttpCommandOptions? commandOptions = null)
        where TResource : IResourceWithEndpoints
    {
        endpointSelector ??= DefaultEndpointSelector(builder);

        var endpoint = endpointSelector()
            ?? throw new DistributedApplicationException($"Could not create HTTP command for resource '{builder.Resource.Name}' as the endpoint selector returned null.");

        if (endpoint.Scheme != "http" && endpoint.Scheme != "https")
        {
            throw new DistributedApplicationException($"Could not create HTTP command for resource '{builder.Resource.Name}' as the endpoint with name '{endpoint.EndpointName}' and scheme '{endpoint.Scheme}' is not an HTTP endpoint.");
        }

        builder.ApplicationBuilder.Services.AddHttpClient();

        commandOptions ??= HttpCommandOptions.Default;
        commandOptions.Method ??= HttpMethod.Post;

        commandName ??= $"{endpoint.Resource.Name}-{endpoint.EndpointName}-http-{commandOptions.Method.Method.ToLowerInvariant()}-{path}";

        if (commandOptions.UpdateState is null)
        {
            commandOptions.UpdateState = context =>
            {
                var resourceState = context.ResourceSnapshot.State?.Text;
                var targetRunning = resourceState == KnownResourceStates.Running || resourceState == KnownResourceStates.RuntimeUnhealthy;
                return targetRunning ? ResourceCommandState.Enabled : ResourceCommandState.Disabled;
            };
        }

View on GitHub (pinned to 25830f84bd)