BoundaryML/baml · error

unexpected type for headers: %T

Error message

unexpected type for headers: %T

What it means

Thrown by httpResponse.Headers() when the FFI call succeeded but the decoded result is not a Go map[string]string. The %T verb names the actual decoded type. The core normally encodes headers as a string-to-string map; anything else indicates encoding drift or an unhandled payload shape.

Solutions

1. Upgrade the Go bindings and BAML core to the same release
2. Inspect the %T value and check pkg/cffi map decoding for the missing case
3. Avoid assuming header presence; treat header reads as optional metadata
4. Report the %T to BAML maintainers if versions are aligned

Example fix

headers, err := resp.Headers()
if err != nil {
    return fmt.Errorf("headers not a string map: %w", err)
}

if resp == nil { return errors.New("nil HTTPResponse") }

func asStringMap(v any) map[string]string {
    m, ok := v.(map[string]string)
    if !ok { return map[string]string{} }
    return m
}

headers, err := resp.Headers()
if err != nil {
    if strings.Contains(err.Error(), "unexpected type") {
        return nil, fmt.Errorf("header decode drift: %w", err)
    }
    return nil, err
}

When it happens

Trigger: Calling HTTPResponse.Headers() when the core returns headers in an unexpected representation — e.g. a raw list of pairs, an object wrapper, or nil-ish value not decoded as map[string]string, usually after a version mismatch.

Common situations: Upgraded core with stale Go bindings; headers decoded by a different engine version; custom provider responses with non-standard header containers.

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 body: %T
• unexpected type for body: %T
• unexpected type for class property builder: %T
• unexpected type for class property builders: %T
• unexpected type for class property type: %T

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

Appendix: source

Thrown at engine/language_client_go/pkg/rawobjects_http_response.go:63

	}

	status, ok := result.(int64)
	if !ok {
		return 0, fmt.Errorf("unexpected type for status: %T", result)
	}

	return status, nil
}

func (h *httpResponse) Headers() (map[string]string, error) {
	result, err := raw_objects.CallMethod(h, "headers", nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get headers: %w", err)
	}

	headers, ok := result.(map[string]string)
	if !ok {
		return nil, fmt.Errorf("unexpected type for headers: %T", result)
	}

	return headers, nil
}

func (h *httpResponse) Body() (HTTPBody, error) {
	result, err := raw_objects.CallMethod(h, "body", nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get body: %w", err)
	}

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

	return body, nil
}

View on GitHub (pinned to bd85ce9dee)