apache/beam · error

unable to convert value of

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.

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.

Appendix: 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)