What causes "failed to get usage: %w" in BoundaryML/baml?

Inspect errors.Unwrap to identify the FFI failure mode.

failed to get usage: %w

Error message

failed to get usage: %w

What it means

This error wraps any failure from raw_objects.CallMethod when Usage() fetches the 'usage' attribute of a FunctionLog over the C FFI. Like the other accessors it is a wrapper: the meaningful cause (empty FFI buffer, nil pointer, protobuf unmarshal error, or object decode failure) is in the wrapped error. It means the runtime could not supply a usable usage object.

Source

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

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

	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 {

View on GitHub (pinned to bd85ce9dee)

Solutions

Inspect errors.Unwrap to identify the FFI failure mode.
Access usage within the stream's lifetime; don't cache log objects past request completion.
Run `baml generate` to realign client and runtime versions.
File a bug if the wrapped cause is a decode/unmarshal failure on a valid object.

Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

func isCallMethodFailure(err error) bool {
    return strings.Contains(err.Error(), "failed to call object method")
}

Try / catch

usage, err := fnLog.Usage()
if err != nil {
    log.Printf("Usage unavailable: %v (wrapped: %v)", err, errors.Unwrap(err))
    return fmt.Errorf("baml usage inaccessible: %w", err)
}

Prevention

Inspect the wrapped cause via errors.Unwrap.
Read usage data within the stream's lifetime.
Regenerate the Go client after BAML upgrades.
Avoid sharing functionLog objects across goroutines/processes.

When it happens

Trigger: Calling Usage() on an invalid/freed functionLog; FFI method invocation returning an empty buffer or nil pointer; proto unmarshalling or decodeObjectResponse failing for the usage response.

Common situations: Touching logs after the function stream finished; collector log references held too long; mismatch between generated Go client and BAML runtime versions.

Related errors

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