BoundaryML/baml · error

unexpected type for usage: %T

Error message

unexpected type for usage: %T

What it means

Returned by Usage() when the 'usage' call succeeded but the decoded value failed the `result.(Usage)` assertion — the runtime handed back a Go value of an unexpected concrete type. This is an FFI contract guard indicating a client/runtime representation mismatch, a decoder bug, or object corruption; it is not caused by user input.

Source

Thrown at engine/language_client_go/pkg/rawobjects_function_log.go:91

	}

	timing, ok := result.(Timing)
	if !ok {
		return nil, fmt.Errorf("unexpected type for timing: %T", result)
	}

	return timing, nil
}

func (f *functionLog) Usage() (Usage, error) {
	result, err := raw_objects.CallMethod(f, "usage", nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get usage: %w", err)
	}

	usage, ok := result.(Usage)
	if !ok {
		return nil, fmt.Errorf("unexpected type for usage: %T", result)
	}

	return usage, nil
}

func (f *functionLog) RawLLMResponse() (string, error) {
	result, err := raw_objects.CallMethod(f, "raw_llm_response", nil)
	if err != nil {
		return "", fmt.Errorf("failed to get raw LLM response: %w", err)
	}

	response, ok := result.(string)
	if !ok {
		return "", fmt.Errorf("unexpected type for raw LLM response: %T", result)
	}

	return response, nil
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate the Go client (`baml generate`) to match the installed runtime.
2. Read the %T value in the error to identify the actual returned type.
3. Consume the FunctionLog while its owning stream is still valid.
4. Report upstream with versions and the printed type if it happens on a fresh object.

if fnLog == nil {
    return errors.New("function log is nil; cannot read Usage")
}

func usageIsUsage(v any) bool {
    _, ok := v.(Usage)
    return ok
}

usage, err := fnLog.Usage()
if err != nil {
    if strings.Contains(err.Error(), "unexpected type for usage:") {
        return nil, fmt.Errorf("usage object contract mismatch (version skew?): %w", err)
    }
    return nil, err
}

When it happens

Trigger: usage decodes into a non-Usage raw object variant; version skew between the BAML runtime and the generated Go client; stale/freed functionLog objects yielding garbage decodes.

Common situations: Newer engine with older generated client (field representation changed); logs consumed after stream teardown; decodeObjectResponse returning the wrong variant.

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

• unexpected type for ID: %T
• unexpected type for function name: %T
• unexpected type for log type: %T
• unexpected type for timing: %T
• unexpected type for mime type: %T

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/3ca91e444de3c036. Report an issue: GitHub.