microsoft/aspire · error · ArgumentException

Value must be a parameter resource builder or reference…

Error message

Value must be a parameter resource builder or reference expression.

What it means

This AddSecret overload accepts only two shapes for the secret value: a parameter resource builder (IResourceBuilder<ParameterResource>) or a ReferenceExpression. Any other object type fails the switch and throws ArgumentException naming the 'value' parameter.

Solutions

Convert the value to a ReferenceExpression via ReferenceExpression.Create(...) and pass that.
Wrap the value in a parameter resource: builder.AddParameter(name, value, secret: true), then pass that builder.
Check the available AddSecret overloads and pick the one matching the value type you actually have.

Example fix

// before
kv.AddSecretForPolyglot("connStr", someString);

// after
var expr = ReferenceExpression.Create($"{someParameter}");
kv.AddSecretForPolyglot("connStr", expr);

Defensive patterns

Strategy: type-guard

Validate before calling

if (value is not (IResourceBuilder<ParameterResource> or ReferenceExpression))
{
    throw new ArgumentException("Value must be a parameter resource builder or reference expression.", nameof(value));
}

Type guard

bool IsAcceptableSecretValue(object v) => v is IResourceBuilder<ParameterResource> or ReferenceExpression;

Try / catch

try { kv.AddSecretForPolyglot(name, value); }
catch (ArgumentException ex) when (ex.ParamName == "value") { /* wrap value in ReferenceExpression and retry */ }

Prevention

Check the AddSecret overload signatures before calling.
Normalize all secret values through a single helper that produces ReferenceExpression.
Avoid passing raw strings or other resource builders to this API.

When it happens

Trigger: Calling the polyglot AddSecret API passing something other than IResourceBuilder<ParameterResource> or ReferenceExpression — e.g. a raw string, an IResourceBuilder of another resource type, or a plain object.

Common situations: Developers assume strings or other resource builders are accepted for secret values; confusion between the several AddSecret overloads available on the Key Vault resource.

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.KeyVault/AzureKeyVaultResourceExtensions.cs:279

    /// Adds a secret to the Azure Key Vault
    /// </summary>
    [AspireExport("addSecret")]
    internal static IResourceBuilder<AzureKeyVaultSecretResource> AddSecretForPolyglot(
        this IResourceBuilder<AzureKeyVaultResource> builder,
        [ResourceName] string name,
        [AspireUnion(typeof(IResourceBuilder<ParameterResource>), typeof(ReferenceExpression))] object value,
        string? secretName = null)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(value);

        secretName ??= name;

        return value switch
        {
            IResourceBuilder<ParameterResource> parameterResource => builder.AddSecret(name, secretName, parameterResource),
            ReferenceExpression expression => builder.AddSecret(name, secretName, expression),
            _ => throw new ArgumentException("Value must be a parameter resource builder or reference expression.", nameof(value))
        };
    }

    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a parameter resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="name">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="parameterResource">The parameter resource containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    [AspireExportIgnore(Reason = "Raw ParameterResource overload; use the IResourceBuilder<ParameterResource> variant instead.")]
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string name, ParameterResource parameterResource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(parameterResource);

        ValidateSecretName(name);

View on GitHub (pinned to 25830f84bd)