apache/beam · error

unable to convert key of

Error message

unable to convert key of %v to schema field

What it means

Raised in reflectTypeToFieldType when the input is a pointer and converting its element type (t.Elem()) fails. Despite saying 'key of %v', the pointer branch is converting the pointee — the wrap means 'unable to convert the pointed-to type'. On success the pointer field is marked nullable.

Solutions

1. Inspect the wrapped error for the failing element type.
2. Make the pointee schema-convertible (register a logical type or change its kind).
3. Replace the pointer with a value plus presence field, or drop the field.
4. Flatten excessive pointer nesting (**T), which adds conversion failure points.

Example fix

// before
type Row struct { Opt *map[CustomKey]string }
// after
type Row struct { Opt map[string]string }

if t.Kind() == reflect.Ptr {
    if err := schemaSafe(t.Elem()); err != nil {
        return fmt.Errorf("pointee %v not schema-safe: %w", t.Elem(), err)
    }
}

func isNullableSchemaSafe(t reflect.Type) bool {
    return t.Kind() == reflect.Ptr && schemaSafe(t.Elem()) == nil
}

schm, err := reg.FromType(t)
if err != nil && strings.Contains(err.Error(), "unable to convert key of") && t.Kind() == reflect.Ptr {
    return nil, fmt.Errorf("pointee of %v failed conversion: %w", t, err)
}

When it happens

Trigger: Converting a schema field of pointer type (*T) where T (or something nested inside T) fails reflectTypeToFieldType — e.g. *map[BadKey]string, **T chains, or pointers to unregistered custom structs.

Common situations: Optional fields implemented as pointers in PCollection element structs; nilable custom types used as map values or struct fields; deep pointer nesting.

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

Appendix: source

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

	}
	if ftype != nil {
		return &pipepb.FieldType{
			TypeInfo: &pipepb.FieldType_LogicalType{
				LogicalType: &pipepb.LogicalType{
					Urn:            lID,
					Representation: ftype,
					// TODO(BEAM-9615): Handle type Arguments.
				},
			},
		}, nil
	}

	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,
				},

View on GitHub (pinned to 12126d8942)