BoundaryML/baml · error

failed to get usage: %w

Error message

failed to get usage: %w

What it means

LLMCall.Usage() wraps any error from CallMethod(l, "usage", nil) when reading token-usage information from the LLM call. It means the runtime failed to resolve the "usage" attribute across the FFI boundary. A genuinely absent usage returns (nil, nil); this error indicates a lookup/dispatch failure, typically a stale object handle or runtime error.

Source

Thrown at engine/language_client_go/pkg/rawobjects_llm_call.go:99

		return nil, fmt.Errorf("failed to get http response: %w", err)
	}

	if result == nil {
		return nil, nil
	}

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

	return response, nil
}

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

	if result == nil {
		return nil, nil
	}

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

	return usage, nil
}

func (l *llmCall) Selected() (bool, error) {
	result, err := raw_objects.CallMethod(l, "selected", nil)
	if err != nil {
		return false, fmt.Errorf("failed to get selected: %w", err)

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read Usage() only after the call/stream completes and usage has been reported.
2. Consume the call object within the scope that produced it, before runtime cleanup.
3. Match Go binding and native runtime versions, then regenerate bindings.
4. Treat (nil, nil) as 'usage not available' and only unwrap errors for genuine failures.

Example fix

// before: usage read mid-stream
usage, err := call.Usage()

// after: after completion
final, err := stream.Finish()
if err == nil {
    usage, err := call.Usage()
    if err != nil || usage == nil {
        log.Printf("usage unavailable: %v", err)
    }
}

// Ensure the call completed and usage was reported:
// if !call.Completed() { return errors.New("usage not yet available") }

usage, err := call.Usage()
if err != nil {
    log.Printf("usage unavailable: %v", err)
    return
}
if usage == nil {
    // usage legitimately absent (e.g. provider did not report tokens)
}

When it happens

Trigger: Calling Usage() on an llmCall whose RawObject was freed, or when the runtime errors dispatching the "usage" method — e.g. querying usage before the provider response was fully parsed on runtimes that error rather than return null.

Common situations: Reading usage mid-stream before the provider reported usage; accessing the object after runtime cleanup; Go binding/native runtime version mismatch.

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

• failed to get client name: %w
• failed to get provider: %w
• failed to get http request: %w
• failed to get http response: %w
• unexpected type for usage: %T

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