microsoft/aspire · error

aspire: dict getter returned unexpected type %T

Error message

aspire: dict getter %q returned unexpected type %T

What it means

resolveDictHandle calls the dict's getter capability over the AppHost transport and requires the result to be a handleReference. Any other returned type breaks the handle-resolution contract and triggers this error, which includes the capability ID and the offending Go type.

Solutions

1. Regenerate Go resource bindings to match the current AppHost protocol version.
2. Inspect the reported %T in the message to identify what the transport actually returned.
3. Confirm no custom code replaces or intercepts the dict getter capability.
4. Align aspire Go package and AppHost versions.

Example fix

// before
dictHandle, err := d.resolveDictHandle(ctx)
// after
result, err := invokeGetter(ctx, d.getterCapabilityID)
if err != nil { return err }
h, ok := result.(handleReference)
if !ok {
    return fmt.Errorf("dict getter %q: got %T; regenerate bindings (expected handleReference)", d.getterCapabilityID, result)
}

func isHandleReference(v any) bool { _, ok := v.(handleReference); return ok }

v, err := dict.Get(ctx, key)
if err != nil {
    return fmt.Errorf("dict handle resolution failed: %w", err)
}

When it happens

Trigger: Performing any dictionary operation that first resolves the handle when the getter returns a non-handleReference payload — contract mismatch between the generated dict wrapper and the AppHost responder.

Common situations: Stale generated code vs newer AppHost, a getter capability implemented incorrectly (returns value map instead of handle), or transport deserialization producing a different concrete type than expected.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• aspire: list getter returned unexpected type %T
• aspire: dict.toObject: unexpected result type %T
• aspire: merge type mismatch: cannot merge
• aspire: : parameter must be one of [ ], got %T
• callback ID missing

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

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Go/Resources/base.go:434

	}
	d.handleMu.Lock()
	cached := d.resolvedHandle
	d.handleMu.Unlock()
	if cached != nil {
		return cached, nil
	}
	if d.getterCapabilityID == "" {
		return d.parent.handle, nil
	}
	result, err := d.parent.client.invokeCapability(ctx, d.getterCapabilityID, map[string]any{
		"context": d.parent.handle.ToJSON(),
	})
	if err != nil {
		return nil, err
	}
	h, ok := result.(handleReference)
	if !ok {
		return nil, fmt.Errorf("aspire: dict getter %q returned unexpected type %T", d.getterCapabilityID, result)
	}
	dictHandle := h.getHandle()
	d.handleMu.Lock()
	d.resolvedHandle = dictHandle
	d.handleMu.Unlock()
	return dictHandle, nil
}

func (d *Dict[K, V]) ToJSON() map[string]any {
	h, err := d.resolveDictHandle(context.Background())
	if err != nil || h == nil {
		return nil
	}
	out := h.ToJSON()
	return map[string]any{"$handle": out["$handle"], "$type": out["$type"]}
}

func (d *Dict[K, V]) Count() (int, error) {

View on GitHub (pinned to 25830f84bd)