apache/beam · error

registering type for field

Error message

registering type for field %v in %v

What it means

This is a wrapped error raised inside Registry.registerType while recursively registering the field types of a struct. When converting a struct's field type fails, registerType wraps the underlying error with the field name and enclosing struct so the developer can locate the offending field. It indicates a nested type within a struct field could not be registered for schema encoding.

Solutions

1. Look at the wrapped (inner) error below this message to find the root cause type/kind.
2. Change the offending struct field to a schema-serializable type (primitives, strings, slices, maps, nested structs, pointers to structs).
3. Register a logical type for the custom type via RegisterLogicalType/beam.RegisterSchemaType before pipeline construction.
4. Mark the field with a schema ignore tag so it is skipped during registration.
5. Upgrade or patch Beam if the kind is genuinely supported but unlisted in reflectKindToTypeMap.

Example fix

// before
type Event struct { ID CustomID }
// after — register the custom type first, or use a convertible field type
beam.RegisterSchemaType(reflect.TypeOf(CustomID{}), "CustomID")
type Event struct { ID CustomID } // now convertible

func schemaSafe(t reflect.Type) error {
  switch reflectx.SkipPtr(t).Kind() {
  case reflect.Struct:
    for i := 0; i < t.NumField(); i++ {
      if err := schemaSafe(t.Field(i).Type); err != nil {
        return fmt.Errorf("field %s: %w", t.Field(i).Name, err)
      }
    }
    return nil
  case reflect.Map:
    return schemaSafe(t.Key())
  case reflect.Slice, reflect.Array, reflect.Ptr:
    return schemaSafe(t.Elem())
  case reflect.Chan, reflect.Func, reflect.Complex64, reflect.Complex128:
    return fmt.Errorf("unsupported kind %v", t.Kind())
  }
  return nil
}

func isStructOrPtrToStruct(t reflect.Type) bool { return reflectx.SkipPtr(t).Kind() == reflect.Struct }

When it happens

Trigger: Calling Registry.FromType (or RegisterDataType/registerType) on a struct whose field contains a nested type that fails registration — e.g. a field whose type reaches an unlisted reflect.Kind, or whose map/slice/pointer element or nested struct conversion fails.

Common situations: Using custom Go types (named primitives, maps of maps, pointer chains) as struct fields in PCollection element types; newly unsupported kinds after a Beam upgrade; third-party struct fields containing exotic types.

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

• beam.RegisterSchemaProvider: unsupported type kind for…
• cannot convert field
• cannot convert to schema. FromType only converts structs to…
• cannot make schema for type
• Logical Types may not be registered with empty interface…

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

Appendix: source

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

		}
		if t != rt {
			// It's only a logical type if it's not a built in primitive type, which is returned by the map.
			r.RegisterLogicalType(ToLogicalType(t.String(), t, rt))
		}
		return nil
	}

	for i := 0; i < t.NumField(); i++ {
		sf := ut.Field(i)
		ignore, _, err := ignoreField(t, sf)
		if err != nil {
			return err
		}
		if ignore {
			continue
		}
		if err := r.registerType(sf.Type, seen); err != nil {
			return errors.Wrapf(err, "registering type for field %v in %v", sf.Name, ut)
		}
	}

	schm, err := r.fromType(ut)
	if err != nil {
		return errors.WithContextf(err, "converting %v to schema", ut)
	}
	synth, err := r.toType(schm)
	if err != nil {
		return errors.WithContextf(err, "converting %v's back to a synthetic type", ut)
	}

	r.addToMaps(synth, ut)
	return nil
}

// registerType must only be called when the r.rwmu write Lock is held.
func (r *Registry) addToMaps(synth, ut reflect.Type) {

View on GitHub (pinned to 12126d8942)