microsoft/aspire · error

aspire: createBuilder returned unexpected type %T

Error message

aspire: createBuilder returned unexpected type %T

What it means

The generated CreateBuilder() invokes the 'createBuilder' capability and expects the result to be a handleReference identifying the new builder. If the returned value is not a handleReference, this error is returned. It guards the initial handshake of the Go client against contract/shape drift.

Solutions

1. Regenerate the Go client from the current AppHost definitions
2. Update the aspire CLI/AppHost and the generated Go package to the same version
3. Inspect AppHost logs to see the actual createBuilder response

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

When it happens

Trigger: Calling CreateBuilder() (or CreateBuilderWithOptions) when the remote createBuilder capability returns nil or a non-handle value.

Common situations: Mismatched AppHost/generated-client versions, an AppHost that errored during builder creation but returned a non-standard payload, or protocol changes without regeneration.

Related errors

• aspire: build returned unexpected type %T
• aspire: 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/b678bbf3133a0ee0. Report an issue: GitHub.

Appendix: source

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

        // directory (not the cwd) when matching --apphost <directory> requests.
        WriteLine("\tif projectDirectory, ok := resolved[\"ProjectDirectory\"].(string); !ok || projectDirectory == \"\" {");
        WriteLine("\t\tif projectDirectory := os.Getenv(\"ASPIRE_PROJECT_DIRECTORY\"); projectDirectory != \"\" {");
        WriteLine("\t\t\tresolved[\"ProjectDirectory\"] = projectDirectory");
        WriteLine("\t\t} else if pwd, err := os.Getwd(); err == nil {");
        WriteLine("\t\t\tresolved[\"ProjectDirectory\"] = pwd");
        WriteLine("\t\t}");
        WriteLine("\t}");
        WriteLine("\tif appHostFilePath, ok := resolved[\"AppHostFilePath\"].(string); !ok || appHostFilePath == \"\" {");
        WriteLine("\t\tif appHostFilePath := os.Getenv(\"ASPIRE_APPHOST_FILEPATH\"); appHostFilePath != \"\" { resolved[\"AppHostFilePath\"] = appHostFilePath }");
        WriteLine("\t}");
        WriteLine("\tif dashboardApplicationName, ok := resolved[\"DashboardApplicationName\"].(string); ok && dashboardApplicationName == \"\" {");
        WriteLine("\t\tdelete(resolved, \"DashboardApplicationName\")");
        WriteLine("\t}");
        WriteLine();
        WriteLine($"\tresult, err := c.invokeCapability(context.Background(), \"{AtsConstants.CreateBuilderCapability}\", map[string]any{{\"argsOrOptions\": resolved}})");
        WriteLine("\tif err != nil { return nil, err }");
        WriteLine("\thref, ok := result.(handleReference)");
        WriteLine("\tif !ok { return nil, fmt.Errorf(\"aspire: createBuilder returned unexpected type %T\", result) }");
        WriteLine($"\treturn &{builderImpl}{{resourceBuilderBase: newResourceBuilderBase(href.getHandle(), c)}}, nil");
        WriteLine("}");
        WriteLine();
    }

    private string? GetCreateBuilderOptionsType(AtsContext context)
    {
        // The TypeScript generator uses a DTO named "CreateBuilderOptions" for
        // the createBuilder parameter; mirror that.
        foreach (var dto in context.DtoTypes)
        {
            if (dto.Name.Equals("CreateBuilderOptions", StringComparison.Ordinal)
                && _dtoNames.TryGetValue(dto.TypeId, out var goName))
            {
                return goName;
            }
        }
        return null;

View on GitHub (pinned to 25830f84bd)