microsoft/aspire · error · InvalidOperationException

The endpoint ` ` is not defined for the resource ` `. The…

Error message

The endpoint `{EndpointName}` is not defined for the resource `{Resource.Name}`. The resource has no endpoints defined.

What it means

EndpointReference resolves its EndpointAnnotation by name from the owning resource. When the resource has no endpoint annotations at all, accessing the property throws this InvalidOperationException explaining the resource has no endpoints defined.

Solutions

Call .WithEndpoint(name, ...) (or AddEndpoint) on the resource to define the endpoint before referencing it
Verify the endpoint name spelling exactly matches the registered annotation (endpoint names are case-sensitive strings)
If the endpoint should come from a referenced resource, reference the correct resource's endpoint instead of building a new EndpointReference manually

Example fix

// before
var db = builder.AddPostgres("db").AddDatabase("mydb");
var port = db.Resource.GetEndpoint("http").Port; // no 'http' endpoint exists
// after
var db = builder.AddPostgres("db").WithEndpoint(1432, 5432, "http");
var port = db.Resource.GetEndpoint("http").Port;

Defensive patterns

Strategy: validation

Validate before calling

bool hasEndpoint = resource.Annotations.OfType<EndpointAnnotation>().Any(a => a.Name == "http");
if (!hasEndpoint) throw new ArgumentException("Resource has no 'http' endpoint.");

Type guard

bool TryGetEndpoint(IResource resource, string name, out EndpointAnnotation? endpoint) {
  endpoint = resource.Annotations.OfType<EndpointAnnotation>().FirstOrDefault(a => string.Equals(a.Name, name, StringComparison.Ordinal));
  return endpoint is not null;
}

Try / catch

try { var port = endpointRef.Port; } catch (InvalidOperationException ex) when (ex.Message.Contains("is not defined for the resource")) { /* fall back or report config error */ }

Prevention

Always pair GetEndpoint(name) with a preceding WithEndpoint(name, ...) call
Keep endpoint names in constants shared between registration and reference
Use the resource builder's typed endpoint helpers instead of raw string names when available

When it happens

Trigger: Accessing EndpointReference.EndpointAnnotation (directly or via .Port/.Host/etc.) for an endpoint name that was never added because no WithEndpoint/AddEndpoint-style call registered any endpoint on the resource.

Common situations: Referencing endpoints like builder.CreateResourceBuilder(...).GetEndpoint("http") before WithEndpoint("http") was called; copy-pasted code referencing another resource's endpoint name; conditional endpoint registration skipped at runtime.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/EndpointReference.cs:24

namespace Aspire.Hosting.ApplicationModel;

/// <summary>
/// Represents an endpoint reference for a resource with endpoints.
/// </summary>
[AspireExport(ExposeProperties = true, ExposeMethods = true)]
[DebuggerDisplay("Resource = {Resource.Name}, EndpointName = {EndpointName}, IsAllocated = {IsAllocated}")]
public sealed class EndpointReference : IExpressionValue, IManifestExpressionProvider, IValueProvider, IValueWithReferences
{
    // A reference to the endpoint annotation if it exists.
    private EndpointAnnotation? _endpointAnnotation;
    private bool? _isAllocated;
    private readonly NetworkIdentifier? _contextNetworkId;

    /// <summary>
    /// Gets the endpoint annotation associated with the endpoint reference.
    /// </summary>
    public EndpointAnnotation EndpointAnnotation => GetEndpointAnnotation() ?? throw new InvalidOperationException(ErrorMessage ?? BuildMissingEndpointMessage());

    private string BuildMissingEndpointMessage()
    {
        var availableNames = Resource.Annotations
            .OfType<EndpointAnnotation>()
            .Select(a => a.Name)
            .Where(n => !string.IsNullOrEmpty(n))
            .Distinct(StringComparers.EndpointAnnotationName)
            .ToArray();

        if (availableNames.Length == 0)
        {
            return $"The endpoint `{EndpointName}` is not defined for the resource `{Resource.Name}`. The resource has no endpoints defined.";
        }

        var formattedNames = string.Join(", ", availableNames.Select(static n => $"`{n}`"));
        return $"The endpoint `{EndpointName}` is not defined for the resource `{Resource.Name}`. Available endpoints: {formattedNames}.";
    }

View on GitHub (pinned to 25830f84bd)