BoundaryML/baml · critical

unexpected stream state

Error message

unexpected stream state

What it means

decodeStreamStateType converts a CFFIStreamState enum to the shared StreamState type; any state value outside PENDING/STARTED/DONE triggers this panic. It means the native runtime produced a stream state the Go serde does not recognize.

Source

Thrown at engine/language_client_go/baml_go/serde/decode.go:324

	if !ok {
		panic("error decoding value, checked type not found: " + valueChecked.Name.String())
	}
	checkedValue := reflect.New(goType)
	checkedValue.Elem().FieldByName("Value").Set(decodedValue)
	checkedValue.Elem().FieldByName("Checks").Set(reflect.ValueOf(checks))
	return checkedValue.Elem(), goType
}

func decodeStreamStateType(state cffi.CFFIStreamState) shared.StreamStateType {
	switch state {
	case cffi.CFFIStreamState_PENDING:
		return shared.StreamStatePending
	case cffi.CFFIStreamState_STARTED:
		return shared.StreamStateIncomplete
	case cffi.CFFIStreamState_DONE:
		return shared.StreamStateComplete
	default:
		panic("unexpected stream state")
	}
}

func convertFieldTypeToGoType(fieldType *cffi.CFFIFieldTypeHolder, typeMap TypeMap) reflect.Type {
	if fieldType == nil {
		panic("error decoding value")
	}

	type_ := fieldType.Type

	if _, ok := type_.(*cffi.CFFIFieldTypeHolder_StringType); ok {
		return reflect.TypeOf("")
	}

	if _, ok := type_.(*cffi.CFFIFieldTypeHolder_BoolType); ok {
		return reflect.TypeOf(false)
	}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Upgrade the baml Go bindings and regenerate the client to match the installed runtime version
2. Rebuild your Go binary after upgrading so enum mappings are current
3. Pin the BAML runtime version your client was generated against
4. Report the raw state value to BAML maintainers if versions already match

if state < 0 || state > cffi.CFFIStreamState_DONE { return shared.StreamStatePending }

func knownStreamState(s cffi.CFFIStreamState) bool {
  switch s { case cffi.CFFIStreamState_PENDING, cffi.CFFIStreamState_STARTED, cffi.CFFIStreamState_DONE: return true }
  return false
}

defer func() { if r := recover(); r != nil { log.Printf("unknown stream state; treating as incomplete") } }()

When it happens

Trigger: decodeStreamingStateValue receives a CFFIStreamState from a streaming response whose numeric value is unknown to the compiled Go bindings — classic sign of a newer/older runtime speaking to an older compiled enum.

Common situations: Upgrading the BAML CLI/runtime without rebuilding Go bindings, or a native library returning an uninitialized enum value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unexpected cffi.isCFFIFieldTypeLiteral_Literal: %#v
• invalid media type: '%s'
• undefined enum: {enum_name}
• undefined variant: {enum_name}.{variant}
• undefined enum variant: {name}.{field}

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