microsoft/aspire · error · ArgumentOutOfRangeException

Random walk offset must be within the configured range size.

Error message

Random walk offset must be within the configured range size.

What it means

Thrown in the ProxylessEndpointPortAllocator constructor when the randomWalkOffset is negative or greater than or equal to the computed range size (rangeEnd - rangeStart + 1). The allocator uses offset + coprime step to walk the port range deterministically, so the offset must land inside the range.

Solutions

Clamp the offset before construction: randomWalkOffset % (rangeEnd - rangeStart + 1).
Recompute the offset from the current range rather than reusing persisted state from an older configuration.
Validate that offset < rangeEnd - rangeStart + 1 in the config-loading code with a clear error.

Example fix

// before
var allocator = new ProxylessEndpointPortAllocator(rangeStart, rangeEnd, offset: 50000);
// after
var rangeSize = rangeEnd - rangeStart + 1;
var allocator = new ProxylessEndpointPortAllocator(rangeStart, rangeEnd, offset: offset % rangeSize);

Defensive patterns

Strategy: validation

Validate before calling

var rangeSize = rangeEnd - rangeStart + 1;
if (offset < 0 || offset >= rangeSize)
    offset %= rangeSize; // clamp into the current range

Try / catch

try { var alloc = new ProxylessEndpointPortAllocator(start, end, offset); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == nameof(offset)) { offset = 0; /* reseed for this range */ }

Prevention

Recompute persisted offsets whenever the port range configuration changes.
Derive the offset as hash % rangeSize so it is always in range.
Store the range alongside the offset and invalidate state when they disagree.

When it happens

Trigger: Constructing ProxylessEndpointPortAllocator with a randomWalkOffset outside [0, rangeSize), e.g. offset 50000 against a 1024-port range, or an offset persisted from a previous configuration with a different (smaller) range.

Common situations: Persisted allocator state (offset) reused after shrinking the configured port range via env/config; computing the offset from a hash modulo the wrong size; off-by-one using offset == rangeSize.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/ProxylessEndpointPortAllocator.cs:69

    {
    }

    internal ProxylessEndpointPortAllocator(int rangeStart, int rangeEnd, Random random, Func<int, ProtocolType, bool> tryProbe)
        : this(rangeStart, rangeEnd, GetRandomOffset(random, rangeStart, rangeEnd), GetRandomCoprimeStep(random, GetRangeSize(rangeStart, rangeEnd)), tryProbe)
    {
    }

    internal ProxylessEndpointPortAllocator(int rangeStart, int rangeEnd, int randomWalkOffset, int randomWalkStep, Func<int, ProtocolType, bool> tryProbe)
    {
        PortRange.ValidateRange(rangeStart, rangeEnd, nameof(rangeStart), nameof(rangeEnd));

        _rangeStart = rangeStart;
        _rangeEnd = rangeEnd;
        _rangeSize = rangeEnd - rangeStart + 1;

        if (randomWalkOffset < 0 || randomWalkOffset >= _rangeSize)
        {
            throw new ArgumentOutOfRangeException(nameof(randomWalkOffset), randomWalkOffset, "Random walk offset must be within the configured range size.");
        }

        if (randomWalkStep < 1 || randomWalkStep > _rangeSize || GreatestCommonDivisor(randomWalkStep, _rangeSize) != 1)
        {
            throw new ArgumentOutOfRangeException(nameof(randomWalkStep), randomWalkStep, "Random walk step must be coprime with the configured range size.");
        }

        // The scan range is dense and bounded, so indexable visited state is cheaper and simpler than
        // hashing individual ports. The default range is only about 23 KB while still giving O(1)
        // lookups for both random-walk and incremental scans.
        _visited = new bool[_rangeSize];
        _randomWalkCursor = randomWalkOffset;
        _randomWalkStep = randomWalkStep;
        _tryProbe = tryProbe;
    }

    public int AllocatePort(EndpointAnnotation endpoint)
    {

View on GitHub (pinned to 25830f84bd)