microsoft/aspire · error · ArgumentException

Address prefix must be a string or a parameter resource…

Error message

Address prefix must be a string or a parameter resource builder.

What it means

AddSubnetForPolyglot requires the subnet addressPrefix to be either a string CIDR or an IResourceBuilder<ParameterResource> (null is not allowed here, unlike AddAzureVirtualNetworkForPolyglot, per the leading ThrowIfNull). Any other type throws this ArgumentException because the method cannot build a Bicep expression from it.

Solutions

1. Pass the prefix as a string CIDR sized for a subnet, e.g. "10.0.1.0/24".
2. Pass an IResourceBuilder<ParameterResource> from builder.AddParameter(...) to make it configurable.
3. Ensure the value is non-null — this overload does not accept null.
4. If the value is untyped (e.g. from JSON), convert with value?.ToString() after validating it is a CIDR string.

Example fix

// before
var subnet = vnet.AddSubnetForPolyglot("subnet-a", 24);

// after
var subnet = vnet.AddSubnetForPolyglot("subnet-a", "10.0.1.0/24");

if (addressPrefix is null) throw new InvalidOperationException("Subnet addressPrefix is required");
bool ok = addressPrefix is string or IResourceBuilder<ParameterResource>;

bool IsSubnetPrefixAccepted(object v) => v is string or IResourceBuilder<ParameterResource>;

try { vnet.AddSubnetForPolyglot(name, rawPrefix); }
catch (ArgumentException ex) when (ex.ParamName == "addressPrefix") { /* supply a string CIDR and retry */ }

When it happens

Trigger: Calling AddSubnetForPolyglot with addressPrefix as an int, double, unwrapped ParameterResource, arbitrary object from JSON deserialization, or a builder of the wrong resource type; also passing null.

Common situations: Polyglot scenarios where the subnet prefix is read from a JSON config and arrives typed as object/number; passing the result of builder.AddParameter without noting it is already an IResourceBuilder<ParameterResource> (that one is valid — the failures are the other shapes); confusing subnet CIDR size expectations.

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

• Address prefix must be omitted, a string, or a parameter…
• Application Insights must be omitted, a location string, a…
• At least one partition key path should be provided.
• Cannot allocate a /29 subnet in virtual network
• Could not generate a unique name for security rule

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Network/AzureVirtualNetworkExtensions.cs:259

    }

    /// <summary>
    /// Adds an Azure subnet resource to an Azure Virtual Network resource.
    /// </summary>
    [AspireExport("addSubnet")]
    internal static IResourceBuilder<AzureSubnetResource> AddSubnetForPolyglot(
        this IResourceBuilder<AzureVirtualNetworkResource> builder,
        [ResourceName] string name,
        [AspireUnion(typeof(string), typeof(IResourceBuilder<ParameterResource>))] object addressPrefix,
        string? subnetName = null)
    {
        ArgumentNullException.ThrowIfNull(addressPrefix);

        return addressPrefix switch
        {
            string addressPrefixValue => AddSubnet(builder, name, addressPrefixValue, subnetName),
            IResourceBuilder<ParameterResource> addressPrefixParameter => AddSubnet(builder, name, addressPrefixParameter, subnetName),
            _ => throw new ArgumentException(
                "Address prefix must be a string or a parameter resource builder.",
                nameof(addressPrefix))
        };
    }

    private static IResourceBuilder<AzureSubnetResource> AddSubnetCore(
        IResourceBuilder<AzureVirtualNetworkResource> builder,
        AzureSubnetResource subnet)
    {
        builder.Resource.Subnets.Add(subnet);

        if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
        {
            // In run mode, we don't want to add the resource to the builder.
            return builder.ApplicationBuilder.CreateResourceBuilder(subnet);
        }

        return builder.ApplicationBuilder.AddResource(subnet)

View on GitHub (pinned to 25830f84bd)