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 selector returned null.

What it means

Thrown by WithHttpHealthCheck when the supplied endpoint selector (or the default selector) returns null, so no endpoint exists to probe. Aspire needs a concrete EndpointReference to build the HTTP health check.

Solutions

1. Add an endpoint to the resource first (WithEndpoint/WithHttpEndpoint) before wiring the health check.
2. Fix the custom selector to return a valid EndpointReference instead of null.
3. Pass the endpoint name explicitly: WithHttpHealthCheck("http") so the default selector finds it.
4. Verify ordering: endpoints declared before WithHttpHealthCheck in the builder chain.

Example fix

// before
var api = builder.AddProject<Projects.Api>("api");
api.WithHttpHealthCheck(e => null); // throws

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

var endpoints = resource.Annotations.OfType<EndpointAnnotation>().ToList();
if (endpoints.Count == 0)
    throw new InvalidOperationException("Add an endpoint (WithHttpEndpoint/WithEndpoint) before WithHttpHealthCheck.");

bool HasHttpEndpoint(IResource r) => r.Annotations.OfType<EndpointAnnotation>().Any(e => e.Scheme is "http" or "https");

try { api.WithHttpHealthCheck("http"); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("endpoint selector returned null"))
{ Console.Error.WriteLine("Declare the endpoint first."); throw; }

When it happens

Trigger: Passing a custom Func<EndpointReference>? endpointSelector that returns null, or relying on the default selector when the resource has no endpoint matching the expected name/scheme.

Common situations: Calling WithHttpHealthCheck on a resource that has no WithEndpoint/WithHttpEndpoint defined yet; a typo'd endpoint name in a lambda; the endpoint is added conditionally at runtime so the selector resolves null.

Related errors

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

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

Appendix: source

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

    /// reporting a healthy status based on the return code returned from the
    /// "/health" path on the backend server.
    /// <code lang="C#">
    /// var builder = DistributedApplication.CreateBuilder(args);
    /// var backend = builder.AddProject&lt;Projects.Backend&gt;("backend");
    /// backend.WithHttpHealthCheck(() => backend.GetEndpoint("https"), path: "/health")
    /// builder.AddProject&lt;Projects.Frontend&gt;("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}'.");
            }

View on GitHub (pinned to 25830f84bd)