apache/beam · error

unable to convert value of %v to schema field

Error message

unable to convert value of %v to schema field

What it means

This error wraps a failure that occurred while converting the value type of a Go map type into a Beam pipepb.FieldType during schema encoding in reflectTypeToFieldType. The Beam schema package can only translate types it understands (atomics, registered logical types, structs, maps, slices); if the map's value type is itself unconvertible, the underlying error is wrapped with this message. It is a propagation wrapper, so the root cause is described by the wrapped error.

Source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/schema/schema.go:601

	}

	t := ot
	switch t.Kind() {
	case reflect.Ptr:
		vt, err := r.reflectTypeToFieldType(t.Elem())
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert key of %v to schema field", ot)
		}
		vt.Nullable = true
		return vt, nil
	case reflect.Map:
		kt, err := r.reflectTypeToFieldType(t.Key())
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert key of %v to schema field", ot)
		}
		vt, err := r.reflectTypeToFieldType(t.Elem())
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert value of %v to schema field", ot)
		}
		return &pipepb.FieldType{
			TypeInfo: &pipepb.FieldType_MapType{
				MapType: &pipepb.MapType{
					KeyType:   kt,
					ValueType: vt,
				},
			},
		}, nil
	case reflect.Struct:
		sch, err := r.structToSchema(t)
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert %v to schema field", ot)
		}
		return &pipepb.FieldType{
			TypeInfo: &pipepb.FieldType_RowType{
				RowType: &pipepb.RowType{
					Schema: sch,

View on GitHub (pinned to 12126d8942)

Solutions

  1. Read the wrapped (inner) error to identify the exact nested type that failed conversion
  2. Change the map value type to a schema-supported type (atomic, slice, map, or struct of supported fields)
  3. Register custom types with schema.RegisterLogicalType (or schema.RegisterAssignableType) so they convert
  4. Implement cache.CustomTypeEncoder/Decoder or use the coder instead of schema encoding if the type cannot be schema-represented

Example fix

// before
type Bad struct { M map[string]func() }
// after
type Good struct { M map[string]string }
Defensive patterns

Strategy: validation

Validate before calling

func isSchemaSafe(t reflect.Type) error {
  switch t.Kind() {
  case reflect.Interface, reflect.Func, reflect.Chan, reflect.UnsafePointer, reflect.Complex128, reflect.Complex64, reflect.Invalid:
    return fmt.Errorf("unsupported kind %v in %v", t.Kind(), t)
  case reflect.Map:
    if err := isSchemaSafe(t.Elem()); err != nil { return err }
    return isSchemaSafe(t.Key())
  case reflect.Slice, reflect.Array:
    return isSchemaSafe(t.Elem())
  case reflect.Struct:
    for i := 0; i < t.NumField(); i++ {
      if err := isSchemaSafe(t.Field(i).Type); err != nil { return err }
    }
  }
  return nil
}

Try / catch

_, err := registry.ToType(s)
var se *serr
if errors.As(err, &se) { /* handle schema conversion failure */ }
if err != nil {
  if strings.Contains(err.Error(), "unable to convert value of") { /* fix map value type */ }
}

Prevention

When it happens

Trigger: Calling beam.RegisterLogicalType or any schema encoding path (structToSchema/ToType round trips) on a Go struct containing a map whose value type is an unsupported kind (interface, func, chan, unsafe.Pointer, complex, or invalid), or a nested struct that fails conversion.

Common situations: Users define a Podo struct with fields like map[string]func() or map[string]SomeUnregisteredStruct and pass the type to beam.ParDo/beam.Create with schema encoding, or after upgrading Beam a previously registered logical type is no longer registered in the new process.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/204e956ce9c0a3dd. Report an issue: GitHub.