apache/beam · error

cannot convert field %v to schema

Error message

cannot convert field %v to schema

What it means

Wraps any error from structFieldToField while converting one struct field, naming the failing field. It means a single field of the struct (its type needing a logical type, map, or nested conversion that fails) prevented the whole struct from becoming a Beam schema. The root cause is always in the wrapped inner error.

Source

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

		schm.Id = getUUID(t)
		r.typeToSchema[t] = schm
		r.idToType[schm.GetId()] = t
		return schm, nil
	}

	fields := make([]*pipepb.Field, 0, t.NumField())
	for i := 0; i < t.NumField(); i++ {
		sf := t.Field(i)
		ignore, isAnon, err := ignoreField(t, sf)
		if err != nil {
			return nil, err
		}
		if ignore {
			continue
		}
		f, err := r.structFieldToField(sf)
		if err != nil {
			return nil, errors.Wrapf(err, "cannot convert field %v to schema", t.Field(i).Name)
		}
		if isAnon {
			f = proto.Clone(f).(*pipepb.Field)
			f.Options = append(f.Options, optGoEmbedded())
		}
		fields = append(fields, f)
	}

	schm := &pipepb.Schema{
		Fields: fields,
		Id:     getUUID(t),
	}
	r.idToType[schm.GetId()] = t
	r.typeToSchema[t] = schm
	return schm, nil
}

func (r *Registry) structFieldToField(sf reflect.StructField) (*pipepb.Field, error) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the wrapped error to identify the exact failing field type.
2. Change the field to a convertible type or register a logical type for it.
3. Add a schema ignore tag (e.g. `beam:"dropped"`) to the offending field if it need not be serialized.
4. Restrict fields to schema-encodable types (primitives, string, time.Time, slices, maps, nested structs/pointers).

Example fix

// before
type Row struct { Fn func() } // unconvertible field
// after
type Row struct {
    Fn func() `beam:"dropped"`
}

for i := 0; i < t.NumField(); i++ {
    if err := schemaSafe(t.Field(i).Type); err != nil {
        return fmt.Errorf("field %s of %v not schema-safe: %w", t.Field(i).Name, t, err)
    }
}

func allFieldsSchemaSafe(t reflect.Type) bool {
    for i := 0; i < t.NumField(); i++ {
        if schemaSafe(t.Field(i).Type) != nil { return false }
    }
    return true
}

schm, err := reg.FromType(t)
if err != nil && strings.Contains(err.Error(), "cannot convert field") {
    var fe *fieldError
    if errors.As(err, &fe) { return nil, fmt.Errorf("fix field %s: %w", fe.Name, err) }
}

When it happens

Trigger: Calling FromType on a struct where some field's type cannot be represented as a schema field: unsupported kinds (chan, func, complex), failing logical-type providers, unconvertible map keys/values, or nested pointer chains failing in reflectTypeToFieldType.

Common situations: PCollection element structs containing exotic field types; fields added by dependency upgrades; embedded or tagged structs misconfigured; unregistered custom types used as fields.

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

• cannot make schema encoder for type %v as it has an embedded
• cannot make schema encoder for type %v as it has unexported
• panicked: %v
• cannot make schema for type %v as it has an embedded field o
• type is of kind %v

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