microsoft/aspire · error

aspire: : parameter must be one of [ ], got %T

Error message

aspire: {methodName}: parameter %q must be one of [{allowed}], got %T

What it means

Generated Go union-typed parameters emit a type switch validating the parameter against its allowed types before sending. If the caller passes a value whose dynamic type is not in the union, this error is raised (and typically stored on the errored builder). It is compile-time-safe validation for Go interfaces used as union types.

Solutions

  1. Pass one of the allowed types listed in the error message, using the generated wrapper/interface implementations
  2. Convert the value to the expected union member type before the call (e.g. wrap a string in the generated string-variant type)
  3. Regenerate the client if you believe the union should include your type

Example fix

// before
builder.WithParam("port", 8080) // int not in union
// after
builder.WithParam("port", "8080") // string is allowed
Defensive patterns

Strategy: type-guard

Validate before calling

switch v := param.(type) {
case string, *SomeUnionMember: // allowed types from error message
	// ok
default:
	return fmt.Errorf("param must be one of the union types, got %T", param)
}

Type guard

func isAllowedUnionMember(v any) bool {
	switch v.(type) {
	case string, int64, *GeneratedVariant: // mirror the union's allowed types
		return true
	}
	return false
}

Try / catch

if err := rb.WithParam("port", p); err != nil { return err } // check immediately
terminal, err := rb.Build()
if err != nil { /* includes union validation failure */ }

Prevention

When it happens

Trigger: Passing a value of a concrete type not listed in the union's allowed types to a generated method parameter, e.g. passing int where the union only accepts string or a specific interface.

Common situations: Passing the wrong primitive (int vs string), passing nil into a non-nil-allowed union, or using a raw value instead of the generated wrapper type for the union member.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.cs:1865

    /// emitted code creates a descriptive error and runs the supplied
    /// errorAction lines (e.g. propagating to a child wrapper) before
    /// returning. Caller is responsible for choosing the right indentation
    /// and the right error action for the surrounding shape (sync vs goroutine).
    /// </summary>
    private void EmitUnionTypeChecks(
        string indent,
        AtsCapabilityInfo capability,
        string methodName,
        IReadOnlyList<string> errorActionLines)
    {
        foreach (var p in GetUnionParameters(capability))
        {
            var paramName = GetLocalIdentifier(p.Name);
            var allowed = GetUnionAllowedTypes(p.Type!);
            WriteLine($"{indent}switch {paramName}.(type) {{");
            WriteLine($"{indent}case {allowed}:");
            WriteLine($"{indent}default:");
            WriteLine($"{indent}\terr := fmt.Errorf(\"aspire: {methodName}: parameter %q must be one of [{allowed}], got %T\", \"{p.Name}\", {paramName})");
            foreach (var line in errorActionLines)
            {
                WriteLine($"{indent}\t{line}");
            }
            WriteLine($"{indent}}}");
        }
    }

    private void EmitUnionAllowedTypesDoc(AtsCapabilityInfo capability)
    {
        foreach (var p in GetUnionParameters(capability))
        {
            var allowed = GetUnionAllowedTypes(p.Type!);
            WriteLine($"// Allowed types for parameter {p.Name}: {allowed}.");
        }
    }

    private string GetUnionAllowedTypes(AtsTypeRef typeRef)

View on GitHub (pinned to 25830f84bd)