microsoft/aspire · error · ArgumentException

Address prefix must be omitted, a string, or a parameter…

Error message

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

What it means

AddAzureVirtualNetworkForPolyglot is the weakly-typed (polyglot) variant of AddAzureVirtualNetwork and accepts the address prefix as null (omit it and let Azure assign), a string CIDR, or an IResourceBuilder<ParameterResource>. It throws this ArgumentException when the argument is any other type, since there is no meaningful conversion. This keeps the string-based polyglot surface type-safe before any Bicep is emitted.

Solutions

1. Pass the address prefix as a string CIDR, e.g. "10.0.0.0/16".
2. Omit/null the argument entirely to let Azure pick the prefix.
3. Wrap a parameter in a resource builder: builder.AddParameter("vnet-prefix") and pass that IResourceBuilder<ParameterResource>.
4. If the value comes from JSON/config, coerce it to string before calling (and validate the CIDR format).

Example fix

// before
var vnet = builder.AddAzureVirtualNetworkForPolyglot("vnet", 10.0);

// after
var vnet = builder.AddAzureVirtualNetworkForPolyglot("vnet", "10.0.0.0/16");

bool isValidPrefix(object? v) => v is null or string or IResourceBuilder<ParameterResource>;

bool IsAddressPrefixAccepted(object? v) => v is null or string or IResourceBuilder<ParameterResource>;

try { builder.AddAzureVirtualNetworkForPolyglot(name, rawPrefix); }
catch (ArgumentException ex) when (ex.ParamName == "addressPrefix") { /* coerce rawPrefix to string or null and retry */ }

When it happens

Trigger: Calling AddAzureVirtualNetworkForPolyglot and passing an object that is not null, string, or IResourceBuilder<ParameterResource> as addressPrefix — e.g. a number/int CIDR, a ParameterResource (unwrapped, not wrapped in a builder), an IResourceBuilder<ContainerResource>, or a deserialized JSON value typed as object.

Common situations: Polyglot AppHosts (JavaScript/Python/TypeScript via aspire) where the address prefix arrives as JSON so '10.0.0.0/16' may deserialize to a non-string; passing a raw ParameterResource instead of builder.AddParameter(...) result; copying a typed-C# call signature incorrectly.

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 a string or a parameter resource…
• 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/b3be9b57d5a56c3f. Report an issue: GitHub.

Appendix: source

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

        return AddAzureVirtualNetworkCore(builder, resource);
    }

    /// <summary>
    /// Adds an Azure Virtual Network resource to the application model.
    /// </summary>
    [AspireExport("addAzureVirtualNetwork")]
    internal static IResourceBuilder<AzureVirtualNetworkResource> AddAzureVirtualNetworkForPolyglot(
        this IDistributedApplicationBuilder builder,
        [ResourceName] string name,
        [AspireUnion(typeof(string), typeof(IResourceBuilder<ParameterResource>))] object? addressPrefix = null)
    {
        return addressPrefix switch
        {
            null => AddAzureVirtualNetwork(builder, name),
            string addressPrefixValue => AddAzureVirtualNetwork(builder, name, addressPrefixValue),
            IResourceBuilder<ParameterResource> addressPrefixParameter => AddAzureVirtualNetwork(builder, name, addressPrefixParameter),
            _ => throw new ArgumentException(
                "Address prefix must be omitted, a string, or a parameter resource builder.",
                nameof(addressPrefix))
        };
    }

    private static IResourceBuilder<AzureVirtualNetworkResource> AddAzureVirtualNetworkCore(
        IDistributedApplicationBuilder builder,
        AzureVirtualNetworkResource resource)
    {
        if (builder.ExecutionContext.IsRunMode)
        {
            // In run mode, we don't want to add the resource to the builder.
            return builder.CreateResourceBuilder(resource);
        }

        return builder.AddResource(resource)
            .WithIconName("Router");
    }

View on GitHub (pinned to 25830f84bd)