microsoft/aspire · error · InvalidOperationException

Cannot allocate a /29 subnet in virtual network

Error message

Cannot allocate a /29 subnet in virtual network '{vnet.Name}' (address space: {vnetAddressPrefix}). No non-overlapping address space is available. Use 'WithAdminDeploymentScriptSubnet' to provide an explicit subnet.

What it means

This error is thrown by SubnetAddressAllocator.AllocateDeploymentScriptSubnet when it cannot find a free /29 block inside the virtual network's address space. A /29 (8 addresses) is the minimum subnet needed for the Azure admin deployment script container. The allocator scans candidates from the top of the range downward and skips any block overlapping existing subnets; if none fits, it fails with guidance to supply an explicit subnet.

Solutions

Call WithAdminDeploymentScriptSubnet to provide an explicit subnet with enough room
Enlarge the vnet address space (e.g. /24 or /16) so a free /29 fits
Remove or shrink existing subnets to free aligned address space
Verify the vnet address prefix is valid IPv4 CIDR with a prefix <= 29

Example fix

// before
var sql = builder.AddAzureSqlServer("sql").WithAdminDeploymentScriptAutoGenSubnet(); // throws when vnet is full
// after
var sql = builder.AddAzureSqlServer("sql")
    .WithAdminDeploymentScriptSubnet("10.0.255.0/29");

Defensive patterns

Strategy: validation

Validate before calling

// vnetAddressPrefix example: "10.0.0.0/16"
var parts = vnetAddressPrefix.Split('/');
var prefix = int.Parse(parts[1]);
if (prefix > 29) throw new InvalidOperationException("Address space too small for a /29 deployment-script subnet");

Prevention

Provide an explicit subnet with WithAdminDeploymentScriptSubnet when the vnet is small or crowded
Use a generous address space (e.g. /16) for development vnets
Keep the deployment-script subnet range reserved so other subnets never take it

When it happens

Trigger: Calling AllocateDeploymentScriptSubnet for a vnet whose address space is too small (smaller than /29), fully consumed by existing subnets, or fragmented so no aligned /29 fits without overlapping.

Common situations: Very small address prefixes (e.g. /30, /29 already used), vnets densely subdivided into subnets, or an address space that leaves no aligned gap for the deployment-script subnet.

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sql/SubnetAddressAllocator.cs:78

        while (candidate >= vnetStart)
        {
            var candidateEnd = candidate + blockSize - 1;

            if (candidateEnd <= vnetEnd && !OverlapsAny(candidate, candidateEnd, existingRanges))
            {
                return $"{UintToIp(candidate)}/{prefixLength}";
            }

            if (candidate < blockSize)
            {
                break; // Prevent underflow
            }

            candidate -= blockSize;
        }

        throw new InvalidOperationException(
            $"Cannot allocate a /29 subnet in virtual network '{vnet.Name}' (address space: {vnetAddressPrefix}). " +
            $"No non-overlapping address space is available. " +
            $"Use 'WithAdminDeploymentScriptSubnet' to provide an explicit subnet.");
    }

    private static bool OverlapsAny(uint start, uint end, List<(uint Start, uint End)> ranges)
    {
        foreach (var (rStart, rEnd) in ranges)
        {
            if (start <= rEnd && rStart <= end)
            {
                return true;
            }
        }

        return false;
    }

View on GitHub (pinned to 25830f84bd)