BoundaryML/baml · error

decodeLiteralValue: valueLiteral is nil

Error message

decodeLiteralValue: valueLiteral is nil

What it means

decodeLiteralValue guards against a nil *cffi.CFFIFieldTypeLiteral and panics with "decodeLiteralValue: valueLiteral is nil". It is reached from Decode when the engine marked a value as LiteralValue but sent no literal payload, indicating an FFI-level invariant violation rather than user data being wrong.

Solutions

1. Upgrade the Go baml runtime and native engine to matching recent versions
2. If reproducible with a minimal .baml file and stable prompt, file a bug with baml including the stack trace
3. As a workaround, change the output type away from bare literals (wrap in a class with a string field) and regenerate

Example fix

// before (baml): bare literal output
function YesNo() "yes" | "no" { ... }

// after: wrap in a class to avoid the literal value path
class Answer {
  value string
}
function YesNo() Answer { ... }
// baml-cli generate

defer func() {
	if r := recover(); r != nil {
		log.Printf("baml literal decode invariant violation — report with stack trace: %v", r)
	}
}()

When it happens

Trigger: Decode receives a *cffi.CFFIValueHolder_LiteralValue whose LiteralValue pointer is nil — e.g. the engine produced an empty/malformed literal value holder due to a bug or version skew.

Common situations: Engine/Go runtime version mismatch; native library edge cases when a LLM output matches a literal type but the payload construction fails; dev builds of the engine.

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

• error decoding type, checked type not found:
• error decoding value:
• error decoding value, type alias not found:
• error decoding value, unknown field type:
• error decoding value, unknown literal type:

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

Appendix: source

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

		return decodeMapValue(value.MapValue, typeMap)
	case *cffi.CFFIValueHolder_UnionVariantValue:
		return decodeUnionValue(value.UnionVariantValue, typeMap)
	case *cffi.CFFIValueHolder_CheckedValue:
		return decodeCheckedValue(value.CheckedValue, typeMap)
	case *cffi.CFFIValueHolder_StreamingStateValue:
		return decodeStreamingStateValue(value.StreamingStateValue, typeMap)
	case *cffi.CFFIValueHolder_LiteralValue:
		return decodeLiteralValue(value.LiteralValue, typeMap)
	case *cffi.CFFIValueHolder_ObjectValue:
		panic("ObjectValue is not yet supported: " + holder.String())
	default:
		panic("error decoding value: " + holder.String())
	}
}

func decodeLiteralValue(valueLiteral *cffi.CFFIFieldTypeLiteral, _ TypeMap) (reflect.Value, reflect.Type) {
	if valueLiteral == nil {
		panic("decodeLiteralValue: valueLiteral is nil")
	}

	switch value := valueLiteral.Literal.(type) {
	case *cffi.CFFIFieldTypeLiteral_BoolLiteral:
		return reflect.ValueOf(value.BoolLiteral.Value), reflect.TypeOf(false)
	case *cffi.CFFIFieldTypeLiteral_IntLiteral:
		return reflect.ValueOf(value.IntLiteral.Value), reflect.TypeOf(int64(0))
	case *cffi.CFFIFieldTypeLiteral_StringLiteral:
		return reflect.ValueOf(value.StringLiteral.Value), reflect.TypeOf("")
	default:
		panic("error decoding value, unknown literal type: " + fmt.Sprintf("%+v", value))
	}
}

View on GitHub (pinned to bd85ce9dee)