What causes "unable to convert %v to schema field" in apache/beam?

Inspect the wrapped error to find which field failed

unable to convert %v to schema field

Error message

unable to convert %v to schema field

What it means

Thrown in reflectTypeToFieldType when a Go struct type cannot be converted to a Beam RowType because r.structToSchema(t) failed. The error wraps the underlying cause (e.g. an embedded/unsupported field, recursion issue, or unregistered logical type) with this message identifying the offending type.

Source

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

		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,
				},
			},
		}, nil
	case reflect.Slice, reflect.Array:
		// Special handling for []byte
		if t == reflectx.ByteSlice {
			return &pipepb.FieldType{
				TypeInfo: &pipepb.FieldType_AtomicType{
					AtomicType: pipepb.AtomicType_BYTES,
				},
			}, nil
		}
		vt, err := r.reflectTypeToFieldType(t.Elem())

View on GitHub (pinned to 12126d8942)

Solutions

Inspect the wrapped error to find which field failed
Remove or replace unsupported fields (interface/func/chan) with concrete schema-convertible types
Register the nested type via schema.RegisterLogicalType or schema.RegisterAssignableType
Flatten or restructure the struct so all fields are schema-representable

Example fix

// before
type Cfg struct { Hooks []func() }
// after
type Cfg struct { HookNames []string }

Defensive patterns

Strategy: validation

Validate before calling

if err := isSchemaSafe(reflect.TypeOf(MyStruct{})); err != nil {
  log.Fatalf("struct not schema-convertible: %v", err)
}

Try / catch

t, err := schema.FromType(reflect.TypeOf(v))
if err != nil {
  return fmt.Errorf("cannot schema-encode %T: %w", v, err)
}

Prevention

Avoid interface{}, func, chan fields in schema-encoded structs
Run a round-trip test (FromType/ToType) per struct in CI
Keep schema-encoded DTOs separate from domain types with behavior

When it happens

Trigger: Schema-encoding any Go struct (via beam.Impulse/Pardo schema coders, ToType/FromType, or RegisterLogicalType) where structToSchema returns an error — typically because one of the struct's fields hit reflectTypeToFieldType failure.

Common situations: A struct contains an unexported-but-referenced unsupported field kind (chan, func, interface), or a nested struct field of a type that is neither registered nor atomic.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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