microsoft/aspire · error · ArgumentException

AllocatedEndpoint must use the same network as the…

Error message

AllocatedEndpoint must use the same network as the networkId parameter

What it means

AddOrUpdateAllocatedEndpoint stores an AllocatedEndpoint under a specific NetworkIdentifier bucket. To keep the snapshot list consistent, the endpoint's own NetworkID must equal the networkId parameter; otherwise endpoints would be filed under the wrong network. A mismatch throws ArgumentException on the endpoint parameter.

Solutions

Pass an AllocatedEndpoint whose NetworkID equals the networkId argument (or construct one with that value).
Derive both from the same source: allocate the endpoint from the same NetworkIdentifier you pass in.
Guard the call: if (endpoint.NetworkID != networkId) fix or skip before calling.

Example fix

// before
annotation.AddOrUpdateAllocatedEndpoint(NetworkIdentifier.Localhost, endpointForDockerNetwork);
// after
var endpoint = new AllocatedEndpoint(annotation, "localhost", port, NetworkIdentifier.Localhost);
annotation.AddOrUpdateAllocatedEndpoint(NetworkIdentifier.Localhost, endpoint);

Defensive patterns

Strategy: validation

Validate before calling

if (endpoint.NetworkID != networkId)
    throw new ArgumentException($"Endpoint network '{endpoint.NetworkID}' does not match target network '{networkId}'.", nameof(endpoint));

Try / catch

try
{
    annotation.AddOrUpdateAllocatedEndpoint(networkId, endpoint);
}
catch (ArgumentException ex) when (ex.ParamName == nameof(endpoint))
{
    logger.LogError(ex, "Endpoint network mismatch: {Message}", ex.Message);
    throw;
}

Prevention

Construct the AllocatedEndpoint from the same NetworkIdentifier you pass to AddOrUpdateAllocatedEndpoint.
Avoid hardcoded NetworkID values in fakes/builders — derive them from the network parameter.
In loops over networks, build the endpoint inside the loop so it always matches the current identifier.
Add a unit test exercising multi-network allocation to catch captured-variable mismatches.

When it happens

Trigger: Calling annotation.AddOrUpdateAllocatedEndpoint(netA, endpointForNetB) — typically passing a network identifier variable that differs from the one used when the endpoint was allocated/resolved.

Common situations: Looping over networks with the loop variable for the key but a stale/captured endpoint from a previous iteration; test fakes constructing endpoints with a hardcoded NetworkID; copying allocation logic between networks after a refactor added multi-network support.

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/f6572c564fcc38c4. Report an issue: GitHub.

Appendix: source

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

        lock (_snapshots)
        {
            if (_snapshots.Any(s => s.NetworkID.Equals(networkId)))
            {
                return false;
            }
            _snapshots.Add(new NetworkEndpointSnapshot(snapshot, networkId));
            return true;
        }
    }

    /// <summary>
    /// Adds or updates an AllocatedEndpoint value associated with a specific network in the snapshot list.
    /// </summary>
    public void AddOrUpdateAllocatedEndpoint(NetworkIdentifier networkId, AllocatedEndpoint endpoint)
    {
        if (endpoint.NetworkID != networkId)
        {
            throw new ArgumentException($"AllocatedEndpoint must use the same network as the {nameof(networkId)} parameter", nameof(endpoint));
        }
        var nes = GetSnapshotFor(networkId);
        nes.Snapshot.SetValue(endpoint);
    }

    /// <summary>
    /// Gets an AllocatedEndpoint for a given network ID, waiting for it to appear if it is not already present.
    /// </summary>
    public Task<AllocatedEndpoint> GetAllocatedEndpointAsync(NetworkIdentifier networkId, CancellationToken cancellationToken = default)
    {
        var nes = GetSnapshotFor(networkId);
        return nes.Snapshot.GetValueAsync(cancellationToken);
    }

    internal bool TryGetAllocatedEndpoint(NetworkIdentifier networkId, [NotNullWhen(true)] out AllocatedEndpoint? endpoint)
    {
        endpoint = null;

View on GitHub (pinned to 25830f84bd)