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

Read the wrapped error and the field name to find the unconvertible field

cannot convert schema field %v to field

Error message

cannot convert schema field %v to field

What it means

Raised in Registry.toType while rebuilding a Go reflect.Struct from a pipepb.Schema: one of the schema fields could not be converted back into a reflect.StructField via fieldToStructField. The error wraps the underlying cause (an unknown FieldType, an unregistered logical type URN, etc.) and names the failing field.

Source

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

	return r.toType(s)
}

// toType must only be called while holding the r.rwmu lock (read or write)
func (r *Registry) toType(s *pipepb.Schema) (reflect.Type, error) {
	if t, ok := r.idToType[s.GetId()]; ok {
		return t, nil
	}
	if lID, ok := fromLogicalOption(s.GetOptions()); ok {
		if lt, ok := r.logicalTypes[lID]; ok {
			return lt.GoType(), nil
		}
	}

	fields := make([]reflect.StructField, 0, len(s.GetFields()))
	for _, sf := range s.GetFields() {
		rf, err := r.fieldToStructField(sf)
		if err != nil {
			return nil, errors.Wrapf(err, "cannot convert schema field %v to field", sf.GetName())
		}
		if checkOptions(sf.Options, optGoEmbeddedUrn) != nil {
			rf.Anonymous = true
		}
		fields = append(fields, rf)
	}
	ret := reflect.StructOf(fields)
	if ut, ok := r.syntheticToUser[ret]; ok {
		ret = ut
	}
	if t := nillableFromOptions(s.GetOptions(), ret); t != nil {
		return t, nil
	}
	return ret, nil
}

func (r *Registry) fieldToStructField(sf *pipepb.Field) (reflect.StructField, error) {
	name := sf.GetName()

View on GitHub (pinned to 12126d8942)

Solutions

Read the wrapped error and the field name to find the unconvertible field
Register the missing logical type (same URN) with schema.RegisterLogicalType before calling ToType
Check for typos or version skew between the schema producer and the Go registry
Replace the field with a standard atomic/row type in the schema producer

Example fix

// before: ToType fails because URN unknown
// after: register it first
schema.RegisterLogicalType(myLogicalTypeProvider{}) // registers urn "acme:ts"

Defensive patterns

Strategy: try-catch

Try / catch

t, err := registry.ToType(s)
if err != nil {
  var fieldName string
  if strings.Contains(err.Error(), "cannot convert schema field") {
    fmt.Sscanf(err.Error(), "cannot convert schema field %s", &fieldName)
  }
  return fmt.Errorf("field %q unconvertible: %w", fieldName, err)
}

Prevention

Ensure every logical-type URN used by producers is registered in the Go process
Keep schema-producing and schema-consuming SDK versions in sync
Validate cross-language schemas against the Go registry in integration tests

When it happens

Trigger: Calling ToType (or registerType/fieldTypeToReflectType paths) on a schema that contains a field whose type is not representable — e.g. a logical type URN not registered in this process, or an atomic type unknown to atomicTypeToReflectType.

Common situations: Cross-language or serialized pipelines whose schemas reference logical types that were never registered on the Go side; schema produced by another SDK (Python/Java) with types Go cannot reconstruct.

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/8d280a2fbf216daa. Report an issue: GitHub.