BoundaryML/baml · error

unexpected type for null type: %T

Error message

unexpected type for null type: %T

What it means

TypeBuilder.Null() in the Go BAML client builds a null FieldType via a callback whose result must implement the Type interface. If the type-checker callback returns something else (nil or a non-Type value), this internal-invariant error is thrown. It signals a bug in the FFI bridge or a nil underlying type-builder, not a user input problem.

Solutions

1. Ensure the baml-py/baml-cli native library version matches the Go client module version (go.mod dependency alignment).
2. Check that the TypeBuilder is created through baml.NewTypeBuilder() with a valid runtime, not a zero-value struct.
3. Regenerate the BAML client (baml-cli generate) so the FFI bindings match your engine version.
4. If it persists with matching versions, file an issue at github.com/boundaryml/baml with the %T value printed.

Example fix

// before
tb := baml.NewTypeBuilder(ctx) // ctx with torn-down runtime
t, err := tb.Null() // -> "unexpected type for null type: <nil>"

// after
rt := baml.NewRuntime(ctx) // fresh, version-matched runtime
tb := baml.NewTypeBuilderFromRuntime(rt)
t, err := tb.Null()

if tb == nil {
    return nil, errors.New("type builder not initialized")
}

func isValidTypeBuilder(tb baml.TypeBuilder) bool { return tb != nil }

t, err := tb.Null()
if err != nil {
    return nil, fmt.Errorf("TypeBuilder.Null failed: %w", err)
}

When it happens

Trigger: Calling TypeBuilder.Null() when the underlying FFI/baml-cli type-builder object is invalid or the internal checkTypeBuilderType helper returns a non-Type value (e.g. nil after a failed baml type creation).

Common situations: Mismatched baml-go-client and baml-cli versions where the FFI returns an unexpected type; calling Null() on a TypeBuilder whose runtime context was torn down; uninitialized baml runtime.

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

• encoding type builder
• unexpected type for bool type: %T
• unexpected type for float type: %T
• unexpected type for int type: %T
• unexpected type for literal bool type: %T

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

Appendix: source

Thrown at engine/language_client_go/pkg/rawobjects_type_builder.go:89

	}

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

	return typ, nil
}

func (tb *typeBuilder) Null() (Type, error) {
	result, err := raw_objects.CallMethod(tb, "null", nil)
	if err != nil {
		return nil, err
	}

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

	return typ, nil
}

// Literal types
func (tb *typeBuilder) LiteralString(value string) (Type, error) {
	args := map[string]interface{}{
		"value": value,
	}
	result, err := raw_objects.CallMethod(tb, "literal_string", args)
	if err != nil {
		return nil, err
	}

	typ, ok := result.(Type)
	if !ok {
		return nil, fmt.Errorf("unexpected type for literal string type: %T", result)

View on GitHub (pinned to bd85ce9dee)