microsoft/aspire · error

aspire: build returned unexpected type %T

Error message

aspire: build returned unexpected type %T

What it means

The generated Build() method on the Go app builder invokes the 'build' capability and asserts the result implements the application interface. If the remote returns a different concrete type, this error is returned. It protects against protocol drift between the AppHost and generated Go client.

Solutions

1. Regenerate the Go client against the current AppHost contract
2. Update aspire CLI/AppHost and Go packages to matching versions
3. Check AppHost logs for why the build capability returned an unexpected value

app, err := b.Build()
if err != nil {
	return fmt.Errorf("build failed: %w", err)
}

When it happens

Trigger: Calling Build() on a generated Go builder when the remote 'build' capability returns a value that does not implement the expected app interface (e.g. nil or an unrelated handle).

Common situations: Version skew between the aspire AppHost and generated Go client, a failing/partial remote build returning an error payload instead of an app handle, or server-side bugs.

Related errors

• aspire: returned unexpected type %T
• aspire: createBuilder returned unexpected type %T
• argument ' ' passed to capability ' ' contains a circular…
• aspire: deep update recursion limit of '32' exceeded
• aspire: : parameter must be one of [ ], got %T

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

Appendix: source

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

            // Synthesize an impl so wrapIfHandle can return a value satisfying
            // the interface even when the metadata doesn't expose the application
            // as a concrete handle type.
            WriteLine($"type {ToCamelCase(appInterface)} struct {{ *resourceBuilderBase }}");
            WriteLine();
        }

        // Build() method on the concrete impl. Sequential model: any prior
        // chain error short-circuits; otherwise invoke the build capability
        // and return the wrapped result.
        WriteLine($"// Build invokes the build capability and returns the running application.");
        WriteLine($"func (b *{builderImpl}) Build() ({appInterface}, error) {{");
        WriteLine("\tif b.err != nil { return nil, b.err }");
        WriteLine($"\tresult, err := b.client.invokeCapability(context.Background(), \"{AtsConstants.BuildCapability}\", map[string]any{{");
        WriteLine("\t\t\"context\": b.handle.ToJSON(),");
        WriteLine("\t})");
        WriteLine("\tif err != nil { return nil, err }");
        WriteLine($"\tapp, ok := result.({appInterface})");
        WriteLine($"\tif !ok {{ return nil, fmt.Errorf(\"aspire: build returned unexpected type %T\", result) }}");
        WriteLine("\treturn app, nil");
        WriteLine("}");
        WriteLine();

        // CreateBuilder factory.
        var createOptionsType = GetCreateBuilderOptionsType(context);
        WriteLine($"// CreateBuilder establishes a connection to the AppHost and returns a new builder.");
        if (createOptionsType is not null)
        {
            WriteLine($"func CreateBuilder(options ...*{createOptionsType}) ({builderInterface}, error) {{");
        }
        else
        {
            WriteLine($"func CreateBuilder() ({builderInterface}, error) {{");
        }
        WriteLine("\tsocketPath := os.Getenv(\"REMOTE_APP_HOST_SOCKET_PATH\")");
        WriteLine("\tif socketPath == \"\" {");
        WriteLine("\t\treturn nil, fmt.Errorf(\"REMOTE_APP_HOST_SOCKET_PATH environment variable not set. Run this application using `aspire run`\")");

View on GitHub (pinned to 25830f84bd)