microsoft/aspire · error · InvalidOperationException

The default AllocatedEndpoint's network ID must match the…

Error message

The default AllocatedEndpoint's network ID must match the EndpointAnnotation network ID ('{_networkId}'). The attempted AllocatedEndpoint belongs to '{value.NetworkID}'.

What it means

EndpointAnnotation's AllocatedEndpoint property (default network slot) validates that any allocated endpoint assigned belongs to the same network as the annotation's own network ID. When the networks differ it throws an InvalidOperationException describing both IDs. This guards an internal invariant so consumers reading AllocatedEndpoint always get an endpoint consistent with the annotation's network.

Solutions

Use AddOrUpdateAllocatedEndpoint(networkId, endpoint) with the matching NetworkIdentifier instead of the default setter.
Ensure the endpoint was allocated for the same network as the annotation before assigning.
Create a fresh AllocatedEndpoint with the correct NetworkID rather than reusing another network's instance.

Example fix

// before
annotation.AllocatedEndpoint = allocatedForOtherNetwork; // NetworkID mismatch
// after
if (allocated.NetworkID == annotation.NetworkId)
    annotation.AllocatedEndpoint = allocated;
else
    annotation.AddOrUpdateAllocatedEndpoint(networkId, allocatedForThisNetwork);

Defensive patterns

Strategy: validation

Validate before calling

if (allocated.NetworkID != annotation.NetworkId)
    throw new InvalidOperationException($"Endpoint '{allocated.EndpointsString}' belongs to network '{allocated.NetworkID}', not '{annotation.NetworkId}'.");

Try / catch

try
{
    annotation.AllocatedEndpoint = allocated;
}
catch (InvalidOperationException ex) when (ex.Message.Contains("network ID must match"))
{
    logger.LogError(ex, "Network mismatch assigning endpoint {Name}: {Message}", annotation.Name, ex.Message);
    throw;
}

Prevention

Prefer AddOrUpdateAllocatedEndpoint with an explicit NetworkIdentifier over the default AllocatedEndpoint setter.
Carry the NetworkIdentifier alongside AllocatedEndpoint instances instead of caching endpoints by name only.
Re-resolve endpoints whenever the active network changes rather than reassigning old ones.
In tests, construct AllocatedEndpoints from the same NetworkIdentifier used for the annotation.

When it happens

Trigger: Setting annotation.AllocatedEndpoint = endpoint where endpoint.NetworkID differs from the annotation's _networkId — e.g. reusing an AllocatedEndpoint resolved for a second network configuration, or copying endpoints across annotations for different networks.

Common situations: Custom orchestrators or test fakes that allocate endpoints for multiple networks and assign the wrong one; caching AllocatedEndpoints by name only and reassigning them after a network switch; refactoring that split networks but kept a single assignment path.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/EndpointAnnotation.cs:373

            }

            // This looks bad *BUT* we check if the value is set before resolving.
            // This preserves the semantics that if the value is not set, we return null to
            // the caller.
            return AllocatedEndpointSnapshot.GetValueAsync().GetAwaiter().GetResult();
        }
        set
        {
            if (value is null)
            {
                // Setting null will proactively set an exception on the snapshot.
                AllocatedEndpointSnapshot.SetException(new InvalidOperationException($"The endpoint `{Name}` is not allocated"));
            }
            else
            {
                if (_networkId != value.NetworkID)
                {
                    throw new InvalidOperationException($"The default AllocatedEndpoint's network ID must match the EndpointAnnotation network ID ('{_networkId}'). The attempted AllocatedEndpoint belongs to '{value.NetworkID}'.");
                }
                AllocatedEndpointSnapshot.SetValue(value);
            }
        }
#pragma warning restore CS0618 // Type or member is obsolete
    }

    /// <summary>
    /// Gets the <see cref="AllocatedEndpointSnapshot"/> for the default <see cref="AllocatedEndpoint"/>.
    /// </summary>
    [Obsolete("This property will be marked as internal in future Aspire release. Use AllocatedEndpoint and AllAllocatedEndpoints properties to access and change allocated endpoints associated with an EndpointAnnotation.")]
    public ValueSnapshot<AllocatedEndpoint> AllocatedEndpointSnapshot { get; } = new();

    /// <summary>
    /// Gets the list of all AllocatedEndpoints associated with this Endpoint.
    /// </summary>
    public NetworkEndpointSnapshotList AllAllocatedEndpoints { get; } = new();
}

View on GitHub (pinned to 25830f84bd)