apache/beam · error

unable to convert map value type

Error message

unable to convert map value type

What it means

This error is produced by schema.go's fieldTypeToReflectType when converting a protobuf Schema FieldType with a MapType into a Go reflect.Type. It wraps a lower-level failure returned while converting the map's VALUE type to a reflect.Type (the key type already converted fine). The library throws it because a schema whose value field type cannot be represented in Go cannot be materialized as a struct field.

Source

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

	case *pipepb.FieldType_AtomicType:
		var ok bool
		if t, ok = atomicTypeToReflectType[sft.GetAtomicType()]; !ok {
			return nil, errors.Errorf("unknown atomic type: %v", sft.GetAtomicType())
		}
	case *pipepb.FieldType_ArrayType:
		rt, err := r.fieldTypeToReflectType(sft.GetArrayType().GetElementType(), nil)
		if err != nil {
			return nil, errors.Wrap(err, "unable to convert array element type")
		}
		t = reflect.SliceOf(rt)
	case *pipepb.FieldType_MapType:
		kt, err := r.fieldTypeToReflectType(sft.GetMapType().GetKeyType(), nil)
		if err != nil {
			return nil, errors.Wrap(err, "unable to convert map key type")
		}
		vt, err := r.fieldTypeToReflectType(sft.GetMapType().GetValueType(), nil)
		if err != nil {
			return nil, errors.Wrap(err, "unable to convert map value type")
		}
		t = reflect.MapOf(kt, vt) // Panics for invalid map keys (slices/iterables)
	case *pipepb.FieldType_RowType:
		rt, err := r.toType(sft.GetRowType().GetSchema())
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert row type: %v", sft.GetRowType().GetSchema().GetId())
		}
		t = rt
	// case *pipepb.FieldType_IterableType:
	// TODO(BEAM-9615): handle IterableTypes (eg. CoGBK values)

	case *pipepb.FieldType_LogicalType:
		lst := sft.GetLogicalType()
		identifier := lst.GetUrn()
		lt, ok := r.logicalTypes[identifier]
		if !ok {
			return nil, errors.Errorf("unknown logical type: %v", identifier)
		}

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the wrapped inner error to find which value FieldType failed conversion
2. Register the missing logical type with the schema registry (RegisterLogicalType / known logical types) before decoding
3. Simplify the map value type in your schema (e.g. use RowType of primitives instead of a custom logical type)
4. Update the Beam Go SDK to a version that supports the value field type (see TODO BEAM-9615 iterable support)

Example fix

// before
lt, ok := r.logicalTypes["com.myco.CustomType"] // not registered -> unknown logical type
// after
import "github.com/apache/beam/sdks/go/pkg/beam/core/runtime/graphx/schema"
schema.RegisterLogicalType(myCustomLogicalType{}) // register before decoding

for k, v := range schema.Fields {
  if mt := v.GetType().GetMapType(); mt != nil {
    if err := validateFieldType(mt.GetValueType(), registry); err != nil {
      return fmt.Errorf("map field %q: %w", k, err)
    }
  }
}

func isConvertible(ft *pipepb.FieldType, r *Representer) bool {
  switch ft.GetTypeInfo().(type) {
  case *pipepb.FieldType_RowType:
    return r.hasSchema(ft.GetRowType().GetSchema().GetId())
  case *pipepb.FieldType_LogicalType:
    _, ok := r.logicalTypes[ft.GetLogicalType().GetUrn()]
    return ok
  default:
    return true
  }
}

if t, err := fieldTypeToReflectType(sft, nil); err != nil {
  var unknown schema.UnknownTypeError
  if errors.As(err, &unknown) { /* register logical type and retry */ }
  return fmt.Errorf("field %s: %w", name, err)
}

When it happens

Trigger: Calling fieldTypeToReflectType (via fieldToStructField or recursively) on a *pipepb.FieldType whose MapType.ValueType is a RowType with an invalid schema, an unregistered LogicalType, or otherwise unconvertible FieldType; the inner error propagates up and gets wrapped here.

Common situations: Decoding a pipeline graph whose serialized schema contains map values of logical types not registered in the local logicalTypes registry (e.g. after Beam SDK version changes or custom logical types not registered on the receiving side); remote workers converting schemas created by a Python/Java pipeline.

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

• panicked: %v
• cannot make schema for type %v as it has an embedded field o
• type is of kind %v
• unlisted kind %v for type %v reached.
• Unable to generate coder for schema {schema}

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