microsoft/aspire · error · DistributedApplicationException

Could not create HTTP health check for resource

Error message

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

What it means

Thrown by WithHttpHealthCheck when the selected endpoint's scheme is neither http nor https. The health check performs an HTTP GET, so only HTTP(S) endpoints are valid; other schemes (e.g. tcp) cannot be probed this way.

Solutions

1. Pass the explicit HTTP endpoint name: WithHttpHealthCheck("http").
2. Declare an HTTP endpoint with WithHttpEndpoint (scheme http/https) on the resource.
3. Use WithHealthCheck with a custom IHealthCheck for non-HTTP protocols instead.
4. Check the endpoint's Scheme property in the AppHost before wiring.

Example fix

// before
var redis = builder.AddRedis("redis"); // has tcp endpoint only
redis.WithHttpHealthCheck(); // throws: scheme 'tcp'

// after
var api = builder.AddProject<Projects.Api>("api")
    .WithHttpEndpoint(name: "http");
api.WithHttpHealthCheck("http");

var ep = resource.Annotations.OfType<EndpointAnnotation>()
    .FirstOrDefault(e => e.Scheme is "http" or "https");
if (ep is null)
    throw new InvalidOperationException("WithHttpHealthCheck requires an http/https endpoint.");

bool IsHttpScheme(EndpointReference e) => e.Scheme is "http" or "https";

try { api.WithHttpHealthCheck("http"); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("is not an HTTP endpoint"))
{ Console.Error.WriteLine(ex.Message); throw; }

When it happens

Trigger: Calling WithHttpHealthCheck (explicitly or via default selector) on a resource whose matching endpoint was declared with a non-HTTP scheme, e.g. WithEndpoint(name: "tcp", scheme: "tcp").

Common situations: Resources with mixed endpoints where the default selector picks the wrong (TCP) endpoint; copy-pasted health-check wiring onto a database/cache TCP endpoint; endpoint renamed so the default resolves to the wrong one.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Could not create HTTP health check for resource
• The endpoint ' ' does not exist on the resource ' '.
• Cannot tunnel endpoint
• Connection string is unavailable
• Connection string is unavailable

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

Appendix: source

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

    /// var backend = builder.AddProject<Projects.Backend>("backend");
    /// backend.WithHttpHealthCheck(() => backend.GetEndpoint("https"), path: "/health")
    /// builder.AddProject<Projects.Frontend>("frontend")
    ///        .WithReference(backend).WaitFor(backend);
    /// </code>
    /// </example>
    /// <para>This method is not available in polyglot app hosts. Use the endpointName-based overload instead.</para>
    /// </remarks>
    [AspireExportIgnore(Reason = "Func<EndpointReference> delegate — not ATS-compatible.")]
    public static IResourceBuilder<T> WithHttpHealthCheck<T>(this IResourceBuilder<T> builder, Func<EndpointReference>? endpointSelector, string? path = null, int? statusCode = null) where T : IResourceWithEndpoints
    {
        endpointSelector ??= DefaultEndpointSelector(builder);

        var endpoint = endpointSelector()
            ?? throw new DistributedApplicationException($"Could not create HTTP health check 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 health check for resource '{builder.Resource.Name}' as the endpoint with name '{endpoint.EndpointName}' and scheme '{endpoint.Scheme}' is not an HTTP endpoint.");
        }

        path ??= "/";
        statusCode ??= 200;

        var endpointName = endpoint.EndpointName;

        // Validate that the endpoint exists during allocation to fail fast on misconfiguration.
        builder.OnResourceEndpointsAllocated((_, @event, ct) =>
        {
            if (!endpoint.Exists)
            {
                throw new DistributedApplicationException($"The endpoint '{endpointName}' does not exist on the resource '{builder.Resource.Name}'.");
            }

            return Task.CompletedTask;
        });

View on GitHub (pinned to 25830f84bd)